Skip to main content
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?

FeatureJSONDart
Type SafetyNoYes
IDE AutocompletionLimitedFull
Compile-time ChecksNoYes
Refactoring SupportManualAutomatic
Code OrganizationFilesFunctions & Classes

​
Basic Conversion Rules

​
Widget Types

JSON type fields map to Stac + PascalCase class names:
JSON TypeDart Class
textStacText
containerStacContainer
columnStacColumn
rowStacRow
elevatedButtonStacElevatedButton
scaffoldStacScaffold

​
Action Types

JSON actionType fields map to Stac + PascalCase + Action:
JSON actionTypeDart Class
navigateStacNavigateAction
showDialogStacDialogAction
showSnackBarStacSnackBarAction
networkRequestStacNetworkRequest
setValueStacSetValueAction

​
Step-by-Step Migration

​
Step 1: Simple Widget

Before (JSON): 
{
  "type": "text",
  "data": "Hello, World!"
}
After (Dart): 
StacText(data: 'Hello, World!')

​
Step 2: Widget with Properties

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

JSONDart
"#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:
JSONDart
"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_core/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

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