Installation

• Meet Magic
• Why Magic?
• Requirements
• Installing Magic
• Bootstrapping Your Application
• Wind UI Plugin
• Next Steps

Meet Magic

Magic is Laravel for Flutter. It's a framework built on the belief that mobile app development should be a joy, not a chore. Like Laravel revolutionized PHP development, Magic brings the same elegance and developer happiness to Flutter.

If you've ever used Laravel, you'll feel right at home. Magic provides:

• Eloquent ORM - Beautiful, active-record style database interactions with the same syntax you love.
• Expressive Routing - Define your app's navigation with clean, fluent route definitions.
• Service Container - Powerful dependency injection and service management.
• Facades - Simple, static-like access to core services without the complexity.
• Magic CLI - Artisan-inspired scaffolding for controllers, models, migrations, and more.
• Wind UI - Tailwind CSS-like styling directly in Flutter. No more widget tree nightmares.

Magic strives to provide an amazing developer experience while taking care of the complex infrastructure concerns, so you can focus on building something extraordinary.

Why Magic?

There are many ways to build Flutter apps. So why choose Magic?

Magic is a progressive framework, meaning you can start simple and adopt more features as your application grows. Whether you're building a quick MVP or an enterprise-grade application, Magic scales with you.

The Laravel Developer Experience

If you're coming from Laravel, you already know how to use Magic:

// Routing - Feels like home, right?
MagicRoute.get('/users', () => UserController().index());
MagicRoute.get('/users/:id', (id) => UserController().show(id));

// Eloquent - Same beautiful syntax
final users = await User.where('active', true).get();
final user = await User.find(1);
await user.delete();

// HTTP - Clean and simple
final response = await Http.get('/api/users');
if (response.successful) {
  // Handle data
}

No BuildContext Nightmare

One of Flutter's most frustrating aspects is passing BuildContext everywhere. Magic eliminates this entirely:

// Show dialogs from anywhere - controllers, services, even pure Dart!
Magic.success('Done!', 'Profile updated successfully');
Magic.dialog(ConfirmationDialog());
Magic.loading();

// Navigate without context
MagicRoute.to('/dashboard');
MagicRoute.back();

Wind UI - Tailwind for Flutter

Stop wrestling with nested widgets. Build UIs with utility-first classes:

WDiv(
  className: 'flex flex-col p-4 bg-white shadow-lg rounded-xl',
  children: [
    WText('Hello World', className: 'text-xl font-bold text-primary'),
    WButton(
      onTap: () => MagicRoute.to('/next'),
      className: 'bg-blue-500 hover:bg-blue-600 px-4 py-2 rounded-lg',
      child: WText('Get Started', className: 'text-white'),
    ),
  ],
)

Requirements

Magic requires:

• Dart SDK: 3.4.0 or higher
• Flutter: 3.22.0 or higher

Installing Magic

1. Add Dependencies

Add fluttersdk_magic and fluttersdk_wind to your pubspec.yaml:

dependencies:
  fluttersdk_magic:
    git:
      url: https://github.com/fluttersdk/magic.git
  fluttersdk_wind:
    git:
      url: https://github.com/fluttersdk/wind.git

Then run:

flutter pub get

2. Activate Magic CLI

The Magic CLI provides helpful commands for generating code. Activate it globally:

dart pub global activate fluttersdk_magic_cli

[!NOTE] Ensure ~/.pub-cache/bin is in your system PATH to use the magic command globally.

Bootstrapping Your Application

1. Create Configuration

Create a lib/config/app.dart file to export your application configuration:

import 'package:fluttersdk_magic/fluttersdk_magic.dart';

final appConfig = {
  'app': {
    'name': Env.get('APP_NAME', 'Magic App'),
    'debug': Env.get('APP_DEBUG', true),
    'url': Env.get('APP_URL', 'http://localhost'),
    'providers': [
      // Register logic providers here
      // (app) => RouteServiceProvider(app),
    ],
  }
};

2. Initialize in Main

In your lib/main.dart, initialize Magic before running your app:

import 'package:flutter/material.dart';
import 'package:fluttersdk_magic/fluttersdk_magic.dart';
import 'config/app.dart';

void main() async {
  // 1. Ensure Flutter binding is initialized
  WidgetsFlutterBinding.ensureInitialized();

  // 2. Initialize Magic
  await Magic.init(
    envFileName: '.env',
    configFactories: [
      () => appConfig,
    ],
  );

  // 3. Register Routes (if using manual route registration)
  // registerRoutes();

  // 4. Run App
  runApp(const MagicApplication());
}

The Magic.init() method accepts:

Parameter	Type	Description
envFileName	String	Environment file name (default: .env)
configFactories	List	Configuration factory functions
configs	List	Direct configuration maps
providers	List	Additional service providers

3. The Application Widget

Use MagicApplication as your root widget. It handles strict routing, themes, and localization automatically:

class MagicApplication extends StatelessWidget {
  const MagicApplication({super.key});

  @override
  Widget build(BuildContext context) {
    return MagicAppWidget(
      title: Config.get('app.name', 'Magic App'),
      initialRoute: '/',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        useMaterial3: true,
        primarySwatch: Colors.blue,
      ),
    );
  }
}

Wind UI Plugin

Magic includes Wind UI (fluttersdk_wind), a utility-first styling engine inspired by Tailwind CSS. Instead of nesting widgets, you compose UIs with className strings:

WDiv(
  className: 'flex flex-col gap-4 p-6 bg-slate-900 rounded-xl',
  children: [
    WText('Welcome', className: 'text-2xl font-bold text-white'),
    WFormInput(
      controller: emailController,
      label: 'Email',
      placeholder: '[email protected]',
      className: 'w-full bg-slate-800 border border-gray-700 rounded-lg p-3',
    ),
    WButton(
      onTap: () => submit(),
      className: 'bg-primary hover:bg-primary/80 px-4 py-3 rounded-lg',
      child: WText('Sign In', className: 'text-white text-center'),
    ),
  ],
)

[!TIP] See the Wind UI Documentation for the complete widget reference and utility class guide.

Next Steps

Now that you've installed Magic, you may be wondering what to learn next. Here are some recommendations:

• Configuration - Learn how Magic's configuration system works.
• Directory Structure - Understand the recommended project layout.
• Routing - Define your application's navigation.
• Controllers - Handle user interactions and business logic.
• Eloquent ORM - Work with databases the beautiful way.

Welcome to the Magic community. We're excited to see what you'll build!