{"id":47943674,"url":"https://github.com/fluttersdk/magic_starter","last_synced_at":"2026-04-04T08:17:20.324Z","repository":{"id":346679499,"uuid":"1164803202","full_name":"fluttersdk/magic_starter","owner":"fluttersdk","description":"Starter kit for Magic Framework. Auth, Profile, Teams, Notifications — 13 opt-in features with overridable views.","archived":false,"fork":false,"pushed_at":"2026-03-25T21:46:59.000Z","size":507,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-26T05:18:10.338Z","etag":null,"topics":["authentication","flutter","magic","starter-kit"],"latest_commit_sha":null,"homepage":"https://magic.fluttersdk.com/starter","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fluttersdk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-23T13:59:43.000Z","updated_at":"2026-03-25T21:46:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fluttersdk/magic_starter","commit_stats":null,"previous_names":["fluttersdk/magic_starter"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/fluttersdk/magic_starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttersdk%2Fmagic_starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttersdk%2Fmagic_starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttersdk%2Fmagic_starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttersdk%2Fmagic_starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fluttersdk","download_url":"https://codeload.github.com/fluttersdk/magic_starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttersdk%2Fmagic_starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31392536,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","flutter","magic","starter-kit"],"created_at":"2026-04-04T08:17:19.524Z","updated_at":"2026-04-04T08:17:20.310Z","avatar_url":"https://github.com/fluttersdk.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/fluttersdk/magic/master/.github/magic-logo.svg\" width=\"120\" alt=\"Magic Logo\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eMagic Starter\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003ePre-built Auth, Profile, Teams \u0026 Notifications for the Magic Framework.\u003c/strong\u003e\u003cbr/\u003e\n  13 opt-in features — every screen overridable.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pub.dev/packages/magic_starter\"\u003e\u003cimg src=\"https://img.shields.io/pub/v/magic_starter.svg\" alt=\"pub.dev version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/fluttersdk/magic_starter/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/fluttersdk/magic_starter/ci.yml?branch=main\u0026label=CI\" alt=\"CI Status\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License: MIT\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://pub.dev/packages/magic_starter/score\"\u003e\u003cimg src=\"https://img.shields.io/pub/points/magic_starter\" alt=\"pub points\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/fluttersdk/magic_starter/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/fluttersdk/magic_starter?style=flat\" alt=\"GitHub Stars\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://magic.fluttersdk.com/starter\"\u003eWebsite\u003c/a\u003e ·\n  \u003ca href=\"https://magic.fluttersdk.com/packages/starter/getting-started/installation\"\u003eDocs\u003c/a\u003e ·\n  \u003ca href=\"https://pub.dev/packages/magic_starter\"\u003epub.dev\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/fluttersdk/magic_starter/issues\"\u003eIssues\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/fluttersdk/magic_starter/discussions\"\u003eDiscussions\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003e **Alpha** — `magic_starter` is under active development. APIs may change between minor versions until `1.0.0`.\n\n---\n\n## Why Magic Starter?\n\nStop rebuilding authentication, profile management, and team features from scratch in every project. The same screens, the same API calls, the same state management — over and over.\n\n**Magic Starter** gives you production-ready screens for auth, profile, teams, and notifications out of the box. Everything is config-driven with 13 opt-in feature toggles. Every view is overridable via the view registry — swap any screen or layout from your host app without touching the package.\n\n\u003e **Config-driven starter kit.** Enable only what you need. Override any screen. Ship faster.\n\n---\n\n## Features\n\n| | Feature | Description |\n|---|---------|-------------|\n| :key: | **Authentication** | Login, register, forgot/reset password, remember me |\n| :shield: | **Two-Factor Auth** | Enable/disable 2FA with QR code, OTP confirm, recovery codes |\n| :bust_in_silhouette: | **Profile Management** | Photo upload, email/password change, email verification, sessions |\n| :busts_in_silhouette: | **Teams** | Create, switch, invite members, manage roles |\n| :bell: | **Notifications** | Real-time polling, mark read/unread, preference matrix |\n| :iphone: | **OTP Login** | Phone-based guest authentication with send/verify flow |\n| :art: | **Wind UI** | Tailwind-like className system — no Material widgets, dark mode built-in |\n| :package: | **Reusable Widgets** | PageHeader, Card (3 variants), ConfirmDialog (3 variants), PasswordConfirmDialog, TwoFactorModal — all standalone |\n| :gear: | **13 Feature Toggles** | All opt-in, configure only what you need |\n| :jigsaw: | **View Registry** | Override any screen or layout from the host app |\n| :hammer_and_wrench: | **CLI Tools** | install, configure, doctor, publish, uninstall |\n\n---\n\n## Quick Start\n\n### 1. Add the dependency\n\n```yaml\ndependencies:\n  magic_starter: ^0.0.1\n```\n\n### 2. Install configuration\n\n```bash\ndart run magic_starter:install\n```\n\nThis generates `lib/config/magic_starter.dart`, injects `MagicStarterServiceProvider` into `lib/config/app.dart`, and wires the `magicStarterConfig` factory into `lib/main.dart`.\n\n### 3. Boot the provider\n\nThe `MagicStarterServiceProvider` is automatically registered during install. On app boot, it:\n\n- Registers the singleton manager with all customization hooks\n- Defines 9 Gate abilities for section visibility\n- Registers feature-gated routes for auth, profile, teams, and notifications\n- Boots the view registry with default screens and layouts\n\nThat's it — auth, profile, teams, and notifications are ready to use.\n\n---\n\n## Configuration\n\nAfter running the install command, edit `lib/config/magic_starter.dart`:\n\n```dart\nMap\u003cString, dynamic\u003e get magicStarterConfig =\u003e {\n  'magic_starter': {\n    'features': {\n      'teams': false,\n      'profile_photos': false,\n      'registration': true,\n      'two_factor': false,\n      'sessions': false,\n      'guest_auth': false,\n      'phone_otp': false,\n      'newsletter': false,\n      'email_verification': false,\n      'extended_profile': true,\n      'social_login': true,\n      'notifications': true,\n      'timezones': false,\n    },\n    'auth': {\n      'email': true,\n      'phone': false,\n    },\n    'defaults': {\n      'locale': 'en',\n      'timezone': 'UTC',\n    },\n    'routes': {\n      'home': '/',\n      'login': '/auth/login',\n      'auth_prefix': '/auth',\n      'teams_prefix': '/teams',\n      'profile_prefix': '/settings',\n      'notifications_prefix': '/notifications',\n    },\n  },\n};\n```\n\nAll values are read at runtime via `ConfigRepository` — no hardcoded strings scattered across your codebase.\n\n---\n\n## Feature Toggles\n\nAll 13 features default to `false` (opt-in). Enable only what your app needs:\n\n| Toggle | Description |\n|--------|-------------|\n| `teams` | Team creation, switching, member invitations, role management |\n| `profile_photos` | Profile photo upload and display |\n| `registration` | User registration screen and flow |\n| `two_factor` | Two-factor authentication with QR code, OTP, and recovery codes |\n| `sessions` | Active session listing and revocation |\n| `guest_auth` | Guest-only authentication routes (login without account) |\n| `phone_otp` | Phone-based OTP send/verify login flow |\n| `newsletter` | Newsletter subscribe/unsubscribe toggle |\n| `email_verification` | Email verification notice and resend flow |\n| `extended_profile` | Extended profile fields: phone, timezone, language |\n| `social_login` | Social login buttons (Google, Apple, etc.) |\n| `notifications` | Real-time notification polling, read/unread, preference matrix |\n| `timezones` | Timezone selection via async API search |\n\n---\n\n## View Customization\n\nOverride any screen or layout from your host app using the view registry:\n\n```dart\nMagicStarter.view.register('auth.login', (context) {\n  return const MyCustomLoginView();\n});\n\nMagicStarter.view.register('layout.guest', (context, {required child}) {\n  return MyCustomGuestLayout(child: child);\n});\n```\n\nAll views are resolved through `MagicStarter.view.make('auth.login')` — the registry always wins over defaults.\n\n---\n\n## Reusable Widgets\n\nMagic Starter exports a set of standalone UI widgets that consumer apps can use directly — no internal controller coupling required.\n\n### MagicStarterPageHeader\n\nFull-width page header with title, optional subtitle, optional leading widget, and an `actions` list. Renders `sm:flex-row` responsive layout with a `border-b` divider:\n\n```dart\nMagicStarterPageHeader(\n  title: trans('projects.title'),\n  subtitle: trans('projects.manage_subtitle'),\n  leading: BackButton(),\n  actions: [\n    PrimaryButton(label: trans('projects.new'), onTap: _onCreate),\n  ],\n)\n```\n\n### MagicStarterCard\n\nCard wrapper with optional `title` slot, `noPadding` mode for full-bleed content, and three visual `variant` styles:\n\n| Variant | Appearance |\n|---------|-----------|\n| `CardVariant.surface` _(default)_ | White background, subtle border |\n| `CardVariant.inset` | Gray-50 recessed background, border |\n| `CardVariant.elevated` | White background, drop shadow — no border |\n\n```dart\n// Default surface card with title\nMagicStarterCard(\n  title: 'Team Members',\n  child: memberList,\n)\n\n// Full-bleed elevated card\nMagicStarterCard(\n  variant: CardVariant.elevated,\n  noPadding: true,\n  child: dataTable,\n)\n\n// Inset section card\nMagicStarterCard(\n  variant: CardVariant.inset,\n  title: 'Danger Zone',\n  child: deleteAccountButton,\n)\n```\n\n### MagicStarterPasswordConfirmDialog\n\nStandalone password-confirmation dialog. Pass an `onConfirm` callback that returns `null` on success or an error string to show inline. Works independently of any controller:\n\n```dart\nfinal confirmed = await MagicStarterPasswordConfirmDialog.show(\n  context,\n  title: trans('projects.delete_confirm_title'),\n  description: trans('projects.delete_confirm_description'),\n  onConfirm: (password) async {\n    final error = await ProjectService.deleteProject(id, password: password);\n    return error; // null = success, string = show error inline\n  },\n);\n\nif (confirmed) _removeProject();\n```\n\n### MagicStarterTwoFactorModal\n\nMulti-step 2FA wizard modal. Pass `setupData` (from the enable-2FA endpoint) and an `onConfirm` callback. Works for both initial setup and standalone re-authentication flows:\n\n```dart\nfinal success = await MagicStarterTwoFactorModal.show(\n  context,\n  setupData: response.data, // {secret, qr_svg, recovery_codes}\n  onConfirm: (code) async {\n    return await TwoFactorService.verify(code);\n  },\n);\n```\n\n### Other Exported Widgets\n\n| Widget | Purpose |\n|--------|---------|\n| `MagicStarterAuthFormCard` | Centered card wrapper for auth-adjacent screens (invite accept, onboarding) |\n| `MagicStarterTimezoneSelect` | Searchable timezone dropdown backed by `GET /timezones` |\n| `MagicStarterTeamSelector` | Current-team switcher dropdown with create/settings links |\n| `MagicStarterUserProfileDropdown` | User avatar menu with profile links and logout |\n| `MagicStarterNotificationDropdown` | Bell-icon dropdown with live unread badge and mark-as-read |\n| `MagicStarterSocialDivider` | \"Or continue with\" divider for auth forms |\n\nAll widgets are exported from `package:magic_starter/magic_starter.dart`.\n\n---\n\n## Theming\n\n### Navigation Theme\n\nCustomize navigation colors, the brand/logo, and avatar styles without overriding any screens:\n\n```dart\nMagicStarter.useNavigationTheme(\n  MagicStarterNavigationTheme(\n    // Active nav item — supports independent light/dark tokens\n    activeItemClassName:\n        'active:text-amber-500 active:bg-amber-500/10 dark:active:text-amber-400 dark:active:bg-amber-400/10',\n\n    // Brand: gradient text\n    brandClassName:\n        'text-lg font-bold bg-gradient-to-r from-primary to-accent bg-clip-text text-transparent',\n\n    // Brand: image/SVG logo (overrides brandClassName when set)\n    brandBuilder: (context) =\u003e Image.asset('assets/logo.png', height: 28),\n\n    // Bottom nav active color\n    bottomNavActiveClassName: 'active:text-amber-500 dark:active:text-amber-400',\n\n    // Sidebar user menu avatar\n    avatarClassName: 'bg-amber-500/10 dark:bg-amber-400/10',\n    avatarTextClassName: 'text-sm font-bold text-amber-600 dark:text-amber-400',\n\n    // Profile dropdown trigger avatar\n    dropdownAvatarClassName: 'bg-gradient-to-tr from-amber-500 to-amber-300',\n  ),\n);\n```\n\n### Modal Theme\n\nCustomize dialog and modal styles — confirmation dialogs, password prompts, and two-factor modals all read from this theme:\n\n```dart\nMagicStarter.useModalTheme(\n  MagicStarterModalTheme(\n    containerClassName: 'rounded-2xl bg-white dark:bg-gray-900',\n    titleClassName: 'text-lg font-semibold text-gray-900 dark:text-white',\n    primaryButtonClassName: 'bg-primary hover:bg-primary/90 text-white',\n    dangerButtonClassName: 'bg-red-600 hover:bg-red-700 text-white',\n    maxWidth: 480,\n  ),\n);\n```\n\nAll theme fields are optional — omitted fields fall back to sensible defaults. Call both `useNavigationTheme()` and `useModalTheme()` in `AppServiceProvider.boot()` before any UI is painted.\n\n---\n\n## CLI Tools\n\n| Command | Description |\n|---------|-------------|\n| `dart run magic_starter:install` | Scaffold config, provider, and routes into your Magic project |\n| `dart run magic_starter:configure` | Interactively toggle features and update config |\n| `dart run magic_starter:doctor` | Verify installation, check dependencies, diagnose issues |\n| `dart run magic_starter:publish` | Publish starter views and layouts for full customization |\n| `dart run magic_starter:uninstall` | Remove starter config, provider, and routes from your project |\n\n---\n\n## Architecture\n\n```\nApp launch → MagicStarterServiceProvider.boot()\n  → registers MagicStarterManager singleton\n  → defines 9 Gate abilities (starter.profile, starter.teams, etc.)\n  → reads feature toggles via ConfigRepository\n  → registers feature-gated routes (auth, profile, teams, notifications)\n  → boots view registry with default screens and layouts\n  → views resolve controllers via Magic.findOrPut()\n  → controllers use MagicStateMixin for state flow\n  → Wind UI renders all screens — no Material widgets\n```\n\n**Key patterns:**\n\n| Pattern | Implementation |\n|---------|---------------|\n| Singleton Manager | `MagicStarterManager` — central customization registry |\n| View Registry | `MagicStarterViewRegistry` — string-keyed view builders, host app overrides |\n| Feature Toggles | `MagicStarterConfig` — 13 opt-in flags via `ConfigRepository` |\n| Service Provider | Two-phase bootstrap: `register()` (sync) → `boot()` (async) |\n| IoC Container | All bindings via `Magic.singleton()` / `Magic.findOrPut()` |\n\n---\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Installation](https://magic.fluttersdk.com/packages/starter/getting-started/installation) | Adding the package and running the installer |\n| [Configuration](https://magic.fluttersdk.com/packages/starter/getting-started/configuration) | Config file reference and feature toggles |\n| [Authentication](https://magic.fluttersdk.com/packages/starter/basics/authentication) | Login, register, forgot/reset password, 2FA, OTP |\n| [Profile](https://magic.fluttersdk.com/packages/starter/basics/profile) | Profile management, photo upload, sessions |\n| [Teams](https://magic.fluttersdk.com/packages/starter/basics/teams) | Team creation, switching, invitations, roles |\n| [Notifications](https://magic.fluttersdk.com/packages/starter/basics/notifications) | Real-time polling, preferences, read/unread |\n| [Views \u0026 Layouts](https://magic.fluttersdk.com/packages/starter/basics/views-and-layouts) | View registry, layout system, overriding screens |\n| [CLI Tools](https://magic.fluttersdk.com/packages/starter/basics/cli) | Install, configure, doctor, publish, uninstall |\n| [Manager](https://magic.fluttersdk.com/packages/starter/architecture/manager) | Singleton manager and customization hooks |\n| [Service Provider](https://magic.fluttersdk.com/packages/starter/architecture/service-provider) | Bootstrap lifecycle, Gate abilities, IoC bindings |\n| [View Registry](https://magic.fluttersdk.com/packages/starter/architecture/view-registry) | String-keyed builders and host app overrides |\n\n---\n\n## Contributing\n\nContributions are welcome! Please see the [issues page](https://github.com/fluttersdk/magic_starter/issues) for open tasks or to report bugs.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Write tests following the [TDD flow](#) — red, green, refactor\n4. Ensure all checks pass: `flutter test`, `dart analyze`, `dart format .`\n5. Submit a pull request\n\n---\n\n## License\n\nMagic Starter is open-sourced software licensed under the [MIT License](LICENSE).\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built with care by \u003ca href=\"https://github.com/fluttersdk\"\u003eFlutterSDK\u003c/a\u003e\u003cbr/\u003e\n  \u003csub\u003eIf Magic Starter helps your project, consider giving it a \u003ca href=\"https://github.com/fluttersdk/magic_starter\"\u003estar on GitHub\u003c/a\u003e.\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluttersdk%2Fmagic_starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffluttersdk%2Fmagic_starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluttersdk%2Fmagic_starter/lists"}