Migration Guide: JSON to Dart

This guide helps you migrate existing Stac JSON configurations to the new Dart format. The Dart provides type safety, IDE autocompletion, and a more natural development experience.

Why Migrate to Dart?

Feature	JSON	Dart
Type Safety	No	Yes
IDE Autocompletion	Limited	Full
Compile-time Checks	No	Yes
Refactoring Support	Manual	Automatic
Code Organization	Files	Functions & Classes

Basic Conversion Rules

JSON type fields map to Stac + PascalCase class names:

JSON Type	Dart Class
`text`	`StacText`
`container`	`StacContainer`
`column`	`StacColumn`
`row`	`StacRow`
`elevatedButton`	`StacElevatedButton`
`scaffold`	`StacScaffold`

Action Types

JSON actionType fields map to Stac + PascalCase + Action:

JSON actionType	Dart Class
`navigate`	`StacNavigateAction`
`showDialog`	`StacDialogAction`
`showSnackBar`	`StacSnackBarAction`
`networkRequest`	`StacNetworkRequest`
`setValue`	`StacSetValueAction`

Step-by-Step Migration

Before (JSON):

{
  "type": "text",
  "data": "Hello, World!"
}

After (Dart):

StacText(data: 'Hello, World!')

Before (JSON):

{
  "type": "container",
  "width": 200.0,
  "height": 100.0,
  "color": "#2196F3",
  "child": {
    "type": "text",
    "data": "Content"
  }
}

After (Dart):

StacContainer(
  width: 200.0,
  height: 100.0,
  color: StacColors.blue,
  child: StacText(data: 'Content'),
)

Step 3: Nested Widgets

Before (JSON):

{
  "type": "column",
  "mainAxisAlignment": "center",
  "children": [
    { "type": "text", "data": "Title" },
    { "type": "sizedBox", "height": 16.0 },
    { "type": "text", "data": "Subtitle" }
  ]
}

After (Dart):

StacColumn(
  mainAxisAlignment: StacMainAxisAlignment.center,
  children: [
    StacText(data: 'Title'),
    StacSizedBox(height: 16.0),
    StacText(data: 'Subtitle'),
  ],
)

Step 4: Actions

Before (JSON):

{
  "type": "elevatedButton",
  "child": { "type": "text", "data": "Click Me" },
  "onPressed": {
    "actionType": "navigate",
    "routeName": "/details"
  }
}

After (Dart):

StacElevatedButton(
  child: StacText(data: 'Click Me'),
  onPressed: StacNavigateAction(routeName: '/details'),
)

Step 5: Complex Styles

Before (JSON):

{
  "type": "container",
  "decoration": {
    "color": "#FFFFFF",
    "borderRadius": 16.0,
    "boxShadow": [
      {
        "color": "#000000",
        "blurRadius": 10.0,
        "offset": { "x": 0.0, "y": 4.0 }
      }
    ]
  }
}

After (Dart):

StacContainer(
  decoration: StacBoxDecoration(
    color: StacColors.white,
    borderRadius: StacBorderRadius.all(16.0),
    boxShadow: [
      StacBoxShadow(
        color: StacColors.black,
        blurRadius: 10.0,
        offset: StacOffset(dx: 0.0, dy: 4.0),
      ),
    ],
  ),
)

Common Patterns

Padding/Margin

JSON:

{
  "padding": { "horizontal": 16.0, "vertical": 8.0 }
}

Dart:

padding: StacEdgeInsets.symmetric(horizontal: 16.0, vertical: 8.0)

Colors

JSON	Dart
`"#FFFFFF"`	`StacColors.white`
`"#000000"`	`StacColors.black`
`"#2196F3"`	`StacColors.blue`
`"#4CAF50"`	`StacColors.green`
`"#F44336"`	`StacColors.red`
`"primary"`	`'primary'` (theme color)

Enums

JSON string values become Dart enums:

JSON	Dart
`"center"`	`StacMainAxisAlignment.center`
`"spaceBetween"`	`StacMainAxisAlignment.spaceBetween`
`"contain"`	`StacBoxFit.contain`
`"cover"`	`StacBoxFit.cover`

Full Screen Migration Example

Before (JSON file: home_screen.json):

{
  "type": "scaffold",
  "appBar": {
    "type": "appBar",
    "title": { "type": "text", "data": "Home" }
  },
  "body": {
    "type": "center",
    "child": {
      "type": "column",
      "mainAxisAlignment": "center",
      "children": [
        {
          "type": "text",
          "data": "Welcome!",
          "style": { "fontSize": 24.0, "fontWeight": "bold" }
        },
        { "type": "sizedBox", "height": 16.0 },
        {
          "type": "elevatedButton",
          "child": { "type": "text", "data": "Get Started" },
          "onPressed": {
            "actionType": "navigate",
            "routeName": "/onboarding"
          }
        }
      ]
    }
  }
}

After (Dart file: stac/home_screen.dart):

import 'package:stac/stac_core.dart';

@StacScreen(screenName: 'home_screen')
StacWidget homeScreen() {
  return StacScaffold(
    appBar: StacAppBar(
      title: StacText(data: 'Home'),
    ),
    body: StacCenter(
      child: StacColumn(
        mainAxisAlignment: StacMainAxisAlignment.center,
        children: [
          StacText(
            data: 'Welcome!',
            style: StacTextStyle(
              fontSize: 24.0,
              fontWeight: StacFontWeight.bold,
            ),
          ),
          StacSizedBox(height: 16.0),
          StacElevatedButton(
            child: StacText(data: 'Get Started'),
            onPressed: StacNavigateAction(routeName: '/onboarding'),
          ),
        ],
      ),
    ),
  );
}

Build and Deploy

After migrating, build your Dart to JSON:

# Build all screens
stac build

# Deploy to Stac Cloud
stac deploy

The generated JSON will be placed in stac/.build/.

Tips

Start small: Migrate one screen at a time
Use IDE features: Leverage autocompletion and error checking
Run stac build often: Catch errors early
Compare output: Verify generated JSON matches your expectations
Keep JSON backups: Until you’re confident in your migration

Get Started

Concepts

Guides

Migration Guide: JSON to Dart

Why Migrate to Dart?

Basic Conversion Rules

Widget Types

Action Types

Step-by-Step Migration

Step 1: Simple Widget

Step 2: Widget with Properties

Step 3: Nested Widgets

Step 4: Actions

Step 5: Complex Styles

Common Patterns

Padding/Margin

Colors

Enums

Full Screen Migration Example

Build and Deploy

Tips

​Why Migrate to Dart?

​Basic Conversion Rules

​Widget Types

​Action Types

​Step-by-Step Migration

​Step 1: Simple Widget

​Step 2: Widget with Properties

​Step 3: Nested Widgets

​Step 4: Actions

​Step 5: Complex Styles

​Common Patterns

​Padding/Margin

​Colors

​Enums

​Full Screen Migration Example

​Build and Deploy

​Tips

​Related

Why Migrate to Dart?

Basic Conversion Rules

Widget Types

Action Types

Step-by-Step Migration

Step 1: Simple Widget

Step 2: Widget with Properties

Step 3: Nested Widgets

Step 4: Actions

Step 5: Complex Styles

Common Patterns

Padding/Margin

Colors

Enums

Full Screen Migration Example

Build and Deploy

Tips

Related