Codelessly API
Flutter's widgets and layouts as plain, immutable data, with a JSON format. This is the model behind the Codelessly Editor and the Codelessly SDK: nodes, layouts, variables, conditions, actions, scripts, breakpoints and published apps.

The model, between the Editor and the SDK.
Pure Dart: no Flutter, no network, two small dependencies (collection, meta).
Looking to show Codelessly screens in a Flutter app? Use
codelessly_sdk. It exports this package. Usecodelessly_apion its own to read, build, check or transform layouts without Flutter: servers, CLIs, code generators, tests.
import 'package:codelessly_api/codelessly_api.dart';
Install
dart pub add codelessly_api
Dart 3.12 or newer.
A layout in 30 lines
import 'dart:convert';
import 'package:codelessly_api/codelessly_api.dart';
void main() {
final document = LayoutDocument.fromJson({
'schema': 2,
'id': 'hello',
'roots': ['home'],
'nodes': {
'home': {
'type': 'canvas',
'name': 'Home',
'slots': {'body': 'column'},
'layout': {'width': 390, 'height': 844},
},
'column': {
'type': 'column',
'children': ['title'],
'layout': {'width': {'fill': 390}, 'height': {'fill': 844}, 'padding': 24},
'props': {'spacing': 12, 'crossAxisAlignment': 'start'},
},
'title': {
'type': 'text',
'props': {'text': 'Hello!', 'style': {'fontSize': 24, 'fontWeight': 700}},
},
},
});
// Typed access, with Flutter's names and defaults.
final column = document['column']!;
print(column.prop(FlexProps.spacing)); // 12.0
print(column.prop(FlexProps.mainAxisAlignment)); // MainAxisAlignment.start (Flutter's default)
// Immutable: an edit is a copy. Value equality tells what changed.
final edited = document['title']!.withProp(TextProps.text, 'Hello, world!');
print(edited == document['title']); // false
// Sparse JSON out: defaults aren't written.
print(jsonEncode(edited.toJson()));
}
What is in the model
| Nodes | Node: a widget type, its Layout, Decoration, typed Props, bindings, reactions and behaviors. Immutable, with value equality. |
| Widgets | WidgetSpec: one declaration per widget type (66 of them), with each prop's Flutter name, type and default. Widgets.all, Widgets.of(type). |
| Documents | LayoutDocument: canvases (screens) and every node in one flat map; parents are derived, never stored. |
| Logic | Variable, Condition, Reaction / Trigger / ActionDef (one class per action), ScriptDef, binding paths. |
| Publish | PublishModel, PublishLayout, PublishBundle, Breakpoints, ThemeTokens, AppIdentity, HttpApi. |
| Values | Color, EdgeInsets, BorderRadius, Alignment, BoxConstraints, TextStyle, Paint... with Flutter's names. |
The JSON contract
- Total decoding.
fromJsonnever throws. Unknown keys and unknown node types round-trip; a bad value falls back to its default. - Sparse encoding. A value equal to Flutter's default is not written.
Guide
- The data model
- Widgets and
WidgetSpec - The JSON format
- Building and checking a layout in code
- Logic: variables, conditions, actions, scripts
The example builds a layout with the typed classes, round-trips it through JSON and wraps it as a publish bundle.
Using it with Flutter
Several value types share Flutter's names (Color, EdgeInsets, TextStyle, Alignment...). In a Flutter file,
import this package with a prefix:
import 'package:codelessly_api/codelessly_api.dart' as api;
codelessly_sdk re-exports the model without those types for that reason.
License
BSD 3-Clause. See LICENSE.
Libraries
- auth
- Sign-in: the auth action, as authCatalog.
- codelessly_api
- Flutter's widgets and layouts as plain, immutable data: the core and every first-party feature library, with standardCatalog.
- commerce
- Purchases: paywall configuration and the paywall action, as commerceCatalog.
- core
- The core of the model: nodes, layout, decoration, values, widgets, behaviors, triggers, the core actions, variables, conditions, bindings and scripts, and the Catalog that declares them. It knows no feature library (auth, data, commerce, media, engage, publish, managed components): a renderer-only program imports this alone.
- data
- APIs, storage and cloud data: the cloud query model, HTTP APIs, the data actions and the
cloudandapilist data sources, as dataCatalog. - engage
- Engagement: app events, automations, as engageCatalog.
- managed
- Codelessly-managed components and hosted plugins: masters, versions, channels, rollouts, digests and instances.
- media
- Media: video, embedded video, audio and web view node types; speech, sound, image preloading, capture, print and file downloads actions, as mediaCatalog.
- notation
- The compact notation (docs/design/13-compact-notation.md): the form an agent writes for a small UI, expanded to an ordinary document.
- publish
- Publishing: the publish model, published layouts, app identity and style sheets.
- validate
- Strict validation of layout documents: what the lenient decoders would silently drop, replace or ignore, as typed diagnostics.