Documentation
Contributing
Learn how to contribute Flutter components to FlockUI. We welcome all contributions!
Welcome to FlockUI
Thank you for considering contributing to FlockUI! We're building an open-source Flutter UI component library, and every contribution — whether it's a new component, a bug fix, or a documentation improvement — helps the community grow.
Prerequisites
| Tool | Version | Purpose |
|---|---|---|
| Node.js | v18+ | Running the Next.js website |
| npm | v9+ | Package management |
| Flutter SDK | v3.11+ | Building component previews |
| Git | Any | Version control |
Contribution Overview
Fork the Repository
Click the Fork button on the FlockUI GitHub page to create a copy under your account.
Clone & Install
Clone your fork, add the upstream remote, and run npm install to set up dependencies.
Create Component Directory
Create registry/<component>/<variant>/ and add your Dart component file.
Register Metadata
Add your component's name, tag, color, and description in lib/component-meta.ts.
Build Preview
Run npm run render -- -Component <name> -Variant <variant> to generate a live preview.
Submit a Pull Request
Push your changes and open a PR. I'll review it and merge it once everything looks good.
Project Structure
Understanding the directory layout will help you navigate the codebase:
flockui/
├── registry/ # 📦 Flutter component source files
│ ├── button/
│ │ └── default/
│ │ └── button_default.dart
│ └── toast/
│ └── default/
│ └── toast_default.dart
├── renderer/ # 🎨 Flutter web project for previews
│ └── lib/
│ ├── main.dart
│ └── component.dart # (auto-generated)
├── lib/ # 🧰 Website utilities
│ ├── component-meta.ts # Component metadata registry
│ ├── get-component-code.ts
│ └── get-preview-url.ts
├── app/ # 🌐 Next.js app router pages
├── components/ # 🧩 React components for the website
├── scripts/ # 🔧 Build & preview scripts
└── public/ # 📁 Static assets & built previewsAdding a New Component
1. Create the directory
mkdir -p registry/card/default2. Create the Dart file
Create registry/card/default/card_default.dart with a PreviewComponent class.
3. Register metadata
Add an entry in lib/component-meta.ts:
card: {
name: "Cards",
tag: "Layout",
color: "bg-flutter-purple/10 text-flutter-purple border-flutter-purple/20",
description: "A flexible container for grouping related content and actions.",
},4. Build the preview
npm run render -- -Component card -Variant default5. Verify
Start npm run dev and visit /components/card to see your component.
Component Template
Every component file should follow this structure with header comments:
// FlockUI Component: Button (Default)
// Description: A versatile button widget with multiple variants...
// Category: Elements
// External Dependencies: none
// Author: Your Name (optional)
import 'package:flutter/material.dart';
class PreviewComponent extends StatefulWidget {
const PreviewComponent({super.key});
@override
State<PreviewComponent> createState() => _PreviewComponentState();
}
class _PreviewComponentState extends State<PreviewComponent> {
@override
Widget build(BuildContext context) {
// Your component widget tree goes here
return ElevatedButton(
onPressed: () {},
child: const Text('Click Me'),
);
}
}Code Rules
- Class name must be PreviewComponent: Required by the renderer.
- Use Material 3 widgets: Prefer FilledButton, Card, NavigationBar, etc.
- Keep it self-contained: The entire component in a single .dart file.
- Annotate external dependencies: List them in comments at the top of the file.
Naming Conventions
| Item | Convention | Example |
|---|---|---|
| Component directory | kebab-case | text-field, bottom-sheet |
| Variant directory | kebab-case | default, outline, with-icon |
| Dart file | snake_case | text_field_default.dart |
| Dart class | PascalCase | PreviewComponent (always) |
Contributing to the Website
This guide focuses on contributing Flutter components. If you'd like to contribute to the Next.js website (docs, blog, design improvements), please reach out to me on LinkedIn or email me at sonukumarhansda61@gmail.com so we can discuss the best approach.
Need Help?
If you have questions or run into issues, open an issue on GitHub or email sonukumarhansda61@gmail.com. We're excited to see what you build! 🚀