lark 0.1.0

A light, elegant Dart web framework with file-based routing, reactive state, and SSR/SSG support.

Lark

Lark is a Dart web framework with:

• file-based routing
• fine-grained reactivity (ref, computed, effect)
• composables for async/data/storage
• static pre-rendering (SSG)
• server-side rendering (SSR)
• a built-in CLI for scaffolding, dev, and production builds

Install

dart pub add lark

Quick Start

Create a project:

dart run lark create my_app
cd my_app
dart pub get
lark dev

Open http://localhost:3000.

App Entry

lib/app.dart:

import 'package:lark/lark.dart';
import 'routes.g.dart';

final app = LarkApp(
  routes: routes,
  config: const LarkConfig(name: 'My App'),
  head: const Head(title: 'My App'),
);

web/main.dart:

import 'package:lark/lark.dart';
import 'package:my_app/app.dart';

void main() {
  createApp(app).mount('#app');
}

Dark Mode Setup

Set the Tailwind strategy in lib/app.dart (defaults to selector mode):

final config = LarkConfig(
  name: 'My App',
  tailwind: TailwindConfig(darkMode: DarkMode.selector),
);

Use dark: classes in UI and control preference with useDarkMode():

final theme = useDarkMode();
theme.toggle();      // switch dark/light
theme.setSystem();   // follow OS preference

On web, Lark automatically wires storage and system preference detection when the app mounts.

Reactivity

import 'package:lark/lark.dart';

class CounterPage extends Component {
  final count = ref(0);
  late final doubled = computed(() => count() * 2);

  @override
  Component build() {
    return Column([
      Text('Count: ${count()}'),
      Text('Doubled: ${doubled()}'),
      Button(label: 'Increment', onPressed: () => count.value++),
    ]);
  }
}

Routing

File-based routing

Lark generates lib/routes.g.dart from lib/pages:

• lib/pages/index.dart -> /
• lib/pages/about.dart -> /about
• lib/pages/blog/__slug__/index.dart -> /blog/:slug

Routes are regenerated by lark dev, lark build, and lark codegen.

Runtime router APIs

• useRouter() for push, replace, back, forward, go
• useRoute() for current path/params/query/meta/data
• useParams() and useQueryParams() helpers
• RouterLink for SPA navigation
• RouterOutlet for nested route trees

State, Forms, and Composables

Store

final useCounterStore = defineStore('counter', () {
  final count = ref(0);
  final doubled = computed(() => count() * 2);

  void increment() => count.value++;

  return (count: count, doubled: doubled, increment: increment);
});

Form

final form = useForm({
  'email': field(validators: [required, email]),
  'password': field(validators: [required, minLength(8)]),
});

Built-in composables

• useFetch, useLazyFetch, usePost
• usePagination, useInfiniteScroll, useAsync, usePolling
• useToggle, useDebounce, useThrottle, usePrevious
• useLocalStorage, useSessionStorage, useCookie, useDarkMode
• useQuery, useMutation, useLazyQuery

SEO and Head Tags

• useMeta(...)
• useSeo(...)
• useHead([...])
• app-level Head(...) on LarkApp

Content System

Put content files in lib/content (.md, .yaml, .json) and run codegen.

Generated catalog: lib/content/content.g.dart

final posts = await content.query('blog').search('dart').find();
final one = await content.findOne('my-post-slug');

CLI

lark create <name>
lark dev [--port] [--verbose] [--ssr]
lark build [--wasm | --js]
lark start
lark serve [--port] [--host] [--dir]
lark generate <component|page|store> <name>
lark codegen
lark doctor
lark clean
lark tailwind setup

Pub Score Check

Run the local pub score check with the included helper:

./tool/pana_check.sh

This script currently forces --dartdoc-version "<9.0.0" as a temporary workaround for a pana/dartdoc compatibility issue on Dart 3.11.

Deployment

Static (SPA + pre-rendered pages)

lark build

Deploy build/ to static hosting.

Local check:

lark serve

SSR

lark build also compiles an SSR server binary:

lark build
lark start

lark start runs build/server (host/port from args or .env).

For source-mode SSR in environments with Dart installed:

cd build
dart pub get
dart run bin/server.dart

Split Imports

Use smaller entrypoints when needed:

• package:lark/core.dart
• package:lark/router.dart
• package:lark/store.dart
• package:lark/seo.dart
• package:lark/composables.dart
• package:lark/ssr.dart
• package:lark/web.dart