FlutterJS

Same Flutter Code. Real HTML Output.

For when your Flutter app needs to be found by Google.

Installation • Quick Start • Why FlutterJS? • Documentation

The Problem

Flutter Web is amazing for apps, but terrible for the web:

Flutter Web Issue	Impact
📦 2-5+ MB bundle	Slow initial load, especially on mobile
🔍 Zero SEO	Canvas rendering = invisible to Google
♿ Poor accessibility	No semantic HTML for screen readers
🐢 Slow first paint	WASM/CanvasKit takes time to initialize

Your beautiful Flutter app is invisible to search engines.

The Solution

FlutterJS compiles your Flutter/Dart code to semantic HTML + CSS + JavaScript instead of Canvas/WASM.

┌─────────────────────────────────────────────────────────┐
│ YOUR FLUTTER CODE │
│ │
│ Scaffold( │
│ appBar: AppBar(title: Text('My App')), │
│ body: Center(child: Text('Hello World')), │
│ ) │
└───────────────────────┬─────────────────────────────────┘
│
┌───────────────┴───────────────┐
▼ ▼
Flutter Web FlutterJS
┌─────────────┐ ┌─────────────┐
│ <canvas> │ │ <header> │
│ (pixels) │ │ <main> │
│ 5 MB │ │ <h1> │
│ No SEO │ │ 50 KB │
└─────────────┘ │ Full SEO ✓ │
└─────────────┘

Why FlutterJS?

Feature	Flutter Web	FlutterJS
Code Syntax	Flutter/Dart	Flutter/Dart ✓
Bundle Size	2-5 MB	~50-100 KB
SEO	❌ None	✓ Full
Google Indexable	❌ No	✓ Yes
Accessibility	Poor	Good
Initial Load	3-8 seconds	<1 second
SSR Support	❌ No	✓ Yes
Output	Canvas pixels	Real HTML

Installation

System Requirements

To develop with or use FlutterJS, you need:

Dart SDK: ^3.10.0 or higher (Stable).
Node.js: Required for the JavaScript engine and CLI tools.
NPM: Package manager for JS dependencies.
Git: For managing the monorepo and submodules.
Flutter SDK: (Optional but recommended) For resolving SDK dependencies.

Option 1: npm (Recommended for users)

npm install -g flutterjs

Option 2: From Source (For contributors)

git clone --recursive https://github.com/flutterjsdev/flutterjs.git
cd flutterjs
dart pub global activate --source path .
dart pub get
dart run tool/init.dart

Current Status & Progress

✅ CI/CD Stabilized: Full automation with GitHub Actions, supporting recursive submodules and workspace resolution. ✅ Ecosystem Launch: First official package flutterjs_seo is now live on pub.dev. ✅ Modern Dart Support: Fully compatible with Dart 3.10+ features including dot shorthand and records. ✅ Monorepo Readiness: Standardized workspace structure across all 20+ packages.

Quick Start

1. Create a New Project

flutter create my-app
cd my-app

2. Write Flutter Code

// src/main.dartimport'package:flutter/material.dart';
voidmain() {
runApp(MyApp());
}
classMyAppextendsStatelessWidget {
@overrideWidgetbuild(BuildContext context) {
returnMaterialApp(
home:Scaffold(
appBar:AppBar(title:Text('FlutterJS App')),
body:Center(
child:Text('Hello from FlutterJS!'),
),
),
);
}
}

3. Run Development Server

flutterjs run --to-js --serve

Open http://localhost:3000 — inspect the page to see real HTML elements, not canvas!

4. Build for Production

# Build your application
flutterjs build

This creates a dist/ directory with:

index.html (Entry point)
assets/ (Static resources)
main.js (Compiled app)
vercel.json (Deployment config)

5. Deploy to Vercel

Since flutterjs build automatically generates vercel.json, deployment is zero-config:

# Using Vercel CLI
vercel deploy

Or connect your GitHub repository to Vercel—it will automatically detect the output.

Deployment

Vercel (Recommended)

Deployment is zero-config and optimized for cleanliness (no duplicate node_modules).

Build:
```
flutterjs build
```
(Creates dist/ with app files, keeps dependencies in root)

Deploy:

cd ./build/flutterjs
vercel deploy --prod

The build automatically generates vercel.json and .vercelignore to ensure:

Routing: SPAs work correctly (all routes → index.html)
Dependencies: node_modules are uploaded efficiently
Cleanliness: Your project remains unpolluted

Other Providers

You can deploy the contents of build/flutterjs/dist/ to any static host (Netlify, GitHub Pages, Firebase Hosting). Note: Ensure your provider handles SPA routing (redirect 404s to index.html).

How It Works

FlutterJS intercepts kIsWeb platform checks and routes web-specific code through a lightweight JavaScript runtime instead of Flutter's Canvas/WASM engine.

// Your existing Flutter codeif (kIsWeb) {
// FlutterJS handles this path// Converts to semantic HTML + CSS
}

Architecture

Flutter/Dart Source
│
▼
┌───────────────────┐
│ FlutterJS Parser │ ← Analyzes Dart AST
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Code Generator │ ← Transforms to JavaScript
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ JS Runtime │ ← VNode/VDOM engine
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ HTML + CSS │ ← Semantic, SEO-friendly output
└───────────────────┘

CLI Commands

Command	Description
`flutterjs init <name>`	Create new project
`flutterjs dev`	Start dev server with hot reload
`flutterjs build`	Production build with minification
`flutterjs preview`	Preview production build
`flutterjs --help`	Show all commands

Build Options

flutterjs build --mode ssr # Server-side rendering
flutterjs build --mode csr # Client-side rendering (default)
flutterjs build --mode hybrid # Best of both
flutterjs build -O 0 # Debug build (No optimization / No minification)
flutterjs build -O 3 # Production build (Aggressive optimization)
flutterjs build --output ./dist # Custom output directory

Render Modes

CSR (Client-Side Rendering) — Default

Application renders in the browser. Good for SPAs.

CSR (Client-Side Rendering) — Default

Application renders entirely in the browser using JavaScript.

Best for: Dynamic web apps, Dashboards, Admin panels.
CLI: flutterjs run --target spa (or just flutterjs run)
Config: mode: 'csr'

SSR (Server-Side Rendering)

Pre-renders HTML on the server (build time) and hydrates on the client.

Best for: Marketing sites, Blogs, SEO-critical content.
CLI: flutterjs run --target ssr
Config: mode: 'ssr'
How it works:
1. Build generates a pre-rendered index.html.
2. Client downloads HTML (instant paint).
3. Client hydrates (attaches event listeners).

Hybrid (Coming Soon)

A mix of Static Site Generation (SSG) and SPA.

Best for: Large sites with mixed content.
CLI: flutterjs run --target hybrid
Config: mode: 'hybrid'
Note: Currently experimental. Use SSR for best SEO results.

Supported Widgets

FlutterJS supports the most commonly used Flutter widgets:

Layout

Container, Center, Padding, SizedBox
Row, Column, Stack, Positioned
Expanded, Flexible, Spacer

Material

Scaffold, AppBar, Drawer
ElevatedButton, TextButton, IconButton, FloatingActionButton
Text, Icon, Image
Card, Divider
TextField, Checkbox, Switch

Navigation

Navigator, MaterialPageRoute

State Management

StatefulWidget, setState()
InheritedWidget

More widgets are being added regularly.

Who Should Use FlutterJS?

✅ Use FlutterJS if:

Your Flutter app needs SEO (blogs, e-commerce, marketing sites)
You're targeting low-bandwidth users (smaller bundles matter)
You need Google to index your content
You want semantic HTML for accessibility
First-load performance is critical

❌ Stick with Flutter Web if:

You're building a complex app (games, graphics-heavy)
SEO doesn't matter (internal tools, dashboards)
You need every Flutter widget/feature

Performance

Metric	Flutter Web	FlutterJS
Bundle Size	2-5 MB	~50-100 KB
First Paint	3-8s	<1s
Time to Interactive	5-10s	<2s
Lighthouse SEO	0-30	90-100

Configuration

Create flutterjs.config.js in your project root:

module.exports={// Rendering modemode: 'csr',// 'ssr' | 'csr' | 'hybrid'// Build settingsbuild: {output: 'dist',minify: true,sourcemap: false,},// Dev serverserver: {port: 3000,hot: true,},// Optimizationoptimization: {treeshake: true,splitChunks: true,}};

Project Structure

my-app/
├── flutter.config.js # Configuration
├── package.json
├── src/
│ └── main.dart # Your Flutter code
├── assets/ # Static files (images, fonts)
├── .flutter_js/ # Generated code (auto)
└── dist/ # Production build (generated)

Dart CLI Pipeline

FlutterJS includes a powerful Dart CLI that analyzes your Flutter/Dart code and converts it to optimized JavaScript.

Running the Dart CLI

# Navigate to your Flutter projectcd examples/counter
# Run the full pipeline: Analysis → IR → JavaScript
dart run path/to/flutterjs/bin/flutterjs.dart run --to-js
# With dev server (starts after conversion)
dart run path/to/flutterjs/bin/flutterjs.dart run --to-js --serve
# With custom port
dart run path/to/flutterjs/bin/flutterjs.dart run --to-js --serve --server-port 4000

Pipeline Phases

The Dart CLI executes a multi-phase pipeline:

┌─────────────────────────────────────────────────────────────────┐
│ PHASE 0: Setup & Initialization │
│ • Validate project directory │
│ • Initialize Dart analyzer │
│ • Create output directories │
├─────────────────────────────────────────────────────────────────┤
│ PHASE 1: Static Analysis │
│ • Parse Dart AST │
│ • Build dependency graph │
│ • Detect changed files (incremental) │
├─────────────────────────────────────────────────────────────────┤
│ PHASE 2: IR Generation (5 Passes) │
│ • Pass 1: Declaration Discovery │
│ • Pass 2: Symbol Resolution │
│ • Pass 3: Type Inference │
│ • Pass 4: Control-Flow Analysis │
│ • Pass 5: Validation & Diagnostics │
├─────────────────────────────────────────────────────────────────┤
│ PHASE 3: IR Serialization │
│ • Generate binary IR files │
│ • Save conversion reports │
├─────────────────────────────────────────────────────────────────┤
│ PHASE 4-6: JavaScript Conversion │
│ • Convert IR to JavaScript │
│ • Validate generated code │
│ • Optimize (levels 0-3) │
│ • Write .fjs files │
├─────────────────────────────────────────────────────────────────┤
│ PHASE 7: Dev Server (--serve flag) │
│ • Spawn flutterjs.exe dev server │
│ • Open browser automatically │
│ • Hot reload on file changes │
└─────────────────────────────────────────────────────────────────┘

CLI Options

Flag	Description	Default
`--project, -p`	Path to Flutter project root	`.`
`--source, -s`	Source directory relative to project	`lib`
`--to-js`	Convert IR to JavaScript	`false`
`--serve`	Start dev server after conversion	`false`
`--server-port`	Dev server port	`3000`
`--open-browser`	Open browser automatically	`true`
`--js-optimization-level`	Optimization level (0-3)	`1`
`--validate-output`	Validate generated JavaScript	`true`
`--incremental`	Only reprocess changed files	`true`
`--parallel`	Enable parallel processing	`true`
`--verbose, -v`	Show detailed logs	`false`

Engine Bridge Architecture

FlutterJS uses a bridge architecture to connect the Dart CLI with the JavaScript runtime engine.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│ Dart CLI (flutterjs.dart) │
│ │
│ • Analyzes Dart/Flutter code │
│ • Generates IR (Intermediate Representation) │
│ • Converts IR to .fjs JavaScript files │
│ │
│ After conversion (when --serve is used): │
│ │ │
│ ▼ Process.start() │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ flutterjs.exe dev --port 3000 │ │
│ │ │ │
│ │ • Serves .fjs files via Express.js │ │
│ │ • Hot Module Replacement (HMR) │ │
│ │ • WebSocket for live updates │ │
│ │ • Opens browser automatically │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Browser: http://localhost:3000 │ │
│ │ │ │
│ │ • FlutterJS Runtime loads │ │
│ │ • Widgets render to semantic HTML │ │
│ │ • State management works │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Platform Binaries

The engine bridge automatically detects your platform and uses the appropriate binary:

Platform	Binary
Windows	`flutterjs.exe`
macOS	`flutterjs-macos`
Linux	`flutterjs-linux`

Binaries are located in: packages/flutterjs_engine/dist/

Building Engine Binaries

cd packages/flutterjs_engine
# Build for current platform
npm run build:windows # Windows
npm run build:macos # macOS
npm run build:linux # Linux# Build for all platforms
npm run build:all

Future: IPC Mode (Coming Soon)

The bridge is designed to evolve to a full IPC (Inter-Process Communication) mode:

// Future IPC implementationProcess.start('flutterjs.exe', ['dev', '--ipc']);
// stdin: {"method": "reload", "files": ["main.fjs"]}// stdout: {"status": "ok", "reloadedCount": 1}

✅ Unified Project Structure

The Dart CLI now automatically generates a proper JS project structure in build/flutterjs/:

your-flutter-project/
├── lib/
│ └── main.dart ← Your Flutter/Dart source code
│
└── build/
├── reports/ ← Dart CLI reports (analysis, conversion)
│ ├── conversion_report.json
│ └── summary_report.json
│
└── flutterjs/ ← Generated JS project (where JS CLI runs)
├── flutterjs.config.js ← Auto-generated config
├── package.json ← Auto-generated manifest
├── src/ ← Generated .fjs files
│ └── main.fjs
└── public/ ← Generated HTML
└── index.html

How It Works:

Dart CLI runs from your project root (examples/counter)
Dart CLI analyzes lib/main.dart and converts it to build/flutterjs/src/main.fjs
Dart CLI auto-generates flutterjs.config.js, package.json, and public/index.html
JS CLI runs from build/flutterjs/ (the generated JS project)
Browser opens and your app is running!

Example: Counter App

1. Navigate to the example

cd examples/counter

2. Run the full pipeline with dev server

dart run ../../bin/flutterjs.dart run --to-js --serve

3. Output

┌────────────────────────────────────────────────────────────────┐
│ FLUTTER IR TO JAVASCRIPT CONVERSION PIPELINE (Phases 0-6) │
└────────────────────────────────────────────────────────────────┘
Project: C:\path\to\flutterjs\examples\counter
Source: C:\path\to\flutterjs\examples\counter\lib
Build: C:\path\to\flutterjs\examples\counter\build\flutterjs
PHASE 1: Analyzing project...
Files for conversion: 2
PHASE 2: Generating IR...
✅ main.dart processed
PHASES 4-6: Converting IR to JavaScript...
✅ Generated: 1 files
� Setting up FlutterJS project...
✅ JS project initialized
�🚀 Starting FlutterJS Dev Server...
✅ Dev Server running at http://localhost:3000
📁 Project root: C:\path\to\flutterjs\examples\counter\build\flutterjs
📁 Source files: C:\path\to\flutterjs\examples\counter\build\flutterjs\src
⏳ Server(s) running. Press "q" or Ctrl+C to stop.
🌐 Dev Server: http://localhost:3000

Roadmap

Known Limitations

Method Tear-offs (Callback Context)

Currently, passing methods directly as callbacks (tear-offs) may causing binding issues where this becomes undefined. Workaround: Wrap callbacks in a lambda to preserve context.

// ❌ Avoid (may fail based on transpiler version)
onPressed: _incrementCounter
// ✅ Recommended
onPressed: () =>_incrementCounter()

Initialization

To set up the project for development (both Dart and JavaScript packages), run the following command from the root directory:

# 1. Get Dart dependencies
dart pub get
# 2. Initialize project (installs JS dependencies)
dart run tool/init.dart

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

# Clone the repo
git clone https://github.com/flutterjsdev/flutterjs.git
# Set up the project (Follow 'Initialization' steps above)# 1. dart pub get# 2. dart run tool/init.dart

License

BSD 3-Clause "New" or "Revised" License — see LICENSE for details.

Links

Website: flutterjs.dev
GitHub: github.com/flutterjsdev/flutterjs
Issues: Report a bug
Discussions: Ask questions

FlutterJS
Write Flutter. Ship the Web.

Name		Name	Last commit message	Last commit date
.github		.github
bin		bin
doc		doc
examples		examples
packages		packages
tool		tool
.gitignore		.gitignore
.gitmodules		.gitmodules
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SECURITY.md		SECURITY.md
analysis_options.yaml		analysis_options.yaml
pubspec.yaml		pubspec.yaml

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

FlutterJS

The Problem

Your beautiful Flutter app is invisible to search engines.

The Solution

Why FlutterJS?

Installation

System Requirements

Option 1: npm (Recommended for users)

Option 2: From Source (For contributors)

Current Status & Progress

Quick Start

1. Create a New Project

2. Write Flutter Code

3. Run Development Server

4. Build for Production

5. Deploy to Vercel

Deployment

Vercel (Recommended)

Other Providers

How It Works

Architecture

CLI Commands

Build Options

Render Modes

CSR (Client-Side Rendering) — Default

CSR (Client-Side Rendering) — Default

SSR (Server-Side Rendering)

Hybrid (Coming Soon)

Supported Widgets

Layout

Material

Navigation

State Management

Who Should Use FlutterJS?

Performance

Configuration

Project Structure

Dart CLI Pipeline

Running the Dart CLI

Pipeline Phases

CLI Options

Engine Bridge Architecture

Architecture Overview

Platform Binaries

Building Engine Binaries

Future: IPC Mode (Coming Soon)

✅ Unified Project Structure

Example: Counter App

1. Navigate to the example

2. Run the full pipeline with dev server

3. Output

Roadmap

Known Limitations

Method Tear-offs (Callback Context)

Initialization

Contributing

License

Links

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages