makepad-2-0-migration

name	makepad-2.0-migration
description	CRITICAL: Use for migrating from Makepad 1.x to 2.0. Triggers on: makepad migration, live_design to script_mod, makepad upgrade, makepad 1.x, old syntax, new syntax, makepad breaking changes, makepad 迁移, 旧语法, LiveHook to ScriptHook, apply_over to script_apply_eval, Live to Script, live_design!, angle brackets to curly braces

Makepad 1.x to 2.0 Migration Skill

Version: makepad-widgets (dev branch) | Last Updated: 2026-03-03

Overview

Makepad 2.0 is a fundamental architecture shift from compile-time static DSL to runtime scripting. Migration involves syntax changes, derive macro updates, lifecycle method renames, and new patterns for state management.

Documentation

Refer to the local files for detailed documentation:

• ./references/migration-guide.md - Complete migration reference with examples

---

Quick Syntax Mapping Table

Makepad 1.x	Makepad 2.0	Notes
live_design! { ... }	script_mod! { ... }	Core macro change
<Widget> { ... }	Widget{ ... }	No angle brackets
Key = Value	Key: value	Colon, not equals
(THEME_COLOR)	theme.color_*	Theme namespace
live_body: { ... }	body +: { ... }	Merge operator
#[derive(Live)]	#[derive(Script)]	Derive macro
#[derive(LiveHook)]	#[derive(ScriptHook)]	Lifecycle hooks
#[derive(Widget)]	#[derive(Widget)]	Unchanged
before_apply()	on_before_apply()	Method rename
after_apply()	on_after_apply()	Method rename
apply_over!()	script_apply_eval!()	Runtime updates
DefaultNone	Default	Enum default
LiveRegister	WidgetRegister	Widget registration
live_register()	register_widget(vm)	Registration method
LiveId	LiveId	Unchanged

---

Step-by-Step Migration

Step 1: Replace Macro

// OLD
live_design! {
    import makepad_widgets::base::*;
    import makepad_widgets::theme_desktop_dark::*;

    App = {{App}} {
        ui: <Root> { ... }
    }
}

// NEW
script_mod! {
    use mod.prelude.widgets.*

    startup() do #(App::script_component(vm)){
        ui: Root{
            // ... UI definition
        }
    }
}

Step 2: Update Derives

// OLD
#[derive(Live, LiveHook, Widget)]
pub struct MyWidget { ... }

// NEW
#[derive(Script, ScriptHook, Widget)]
pub struct MyWidget { ... }

Step 3: Update App::run

// OLD
impl LiveRegister for App {
    fn live_register(cx: &mut Cx) {
        makepad_widgets::live_design(cx);
    }
}

// NEW
impl App {
    fn run(vm: &mut ScriptVm) -> Self {
        crate::makepad_widgets::script_mod(vm);
        App::from_script_mod(vm, self::script_mod)
    }
}

Step 4: Rename Lifecycle Methods

// OLD
impl LiveHook for MyWidget {
    fn before_apply(&mut self, cx: &mut Cx, ...) { ... }
    fn after_apply(&mut self, cx: &mut Cx, ...) { ... }
}

// NEW
impl ScriptHook for MyWidget {
    fn on_before_apply(&mut self, cx: &mut Cx, ...) { ... }
    fn on_after_apply(&mut self, cx: &mut Cx, ...) { ... }
}

Step 5: Update DSL Syntax

// OLD - angle brackets, equals signs
<View> {
    width: Fill, height: Fill
    show_bg: true
    draw_bg: { color: (THEME_BG) }

    title = <Label> {
        text: "Hello"
        draw_text: { color: #fff }
    }
}

// NEW - curly braces, colons, theme namespace
View{
    width: Fill height: Fill
    show_bg: true
    draw_bg.color: theme.color_bg_app

    title := Label{
        text: "Hello"
        draw_text.color: #fff
    }
}

Step 6: Replace apply_over with script_eval

// OLD
self.label(id!(title)).apply_over(cx, live! {
    text: "New text"
});

// NEW
script_eval!(cx, {
    ui.title.set_text("New text")
});
// OR
script_apply_eval!(cx, self.ui, {
    title.text: "New text"
});

---

Key Breaking Changes

1. No commas between properties (whitespace-delimited)
2. No semicolons anywhere in Splash
3. No angle brackets for widget types
4. Theme constants use theme.* prefix, not (THEME_*) syntax
5. Named children use := operator, not =
6. Merge operator is +: not : for extending parent properties
7. height: Fit is MANDATORY on containers (default is 0px, not auto)
8. Registration happens in App::run, not live_register
9. Field attribute #[source] links to script object (required on some widgets)
10. Old old/ directory contains archived 1.x code for reference

---

Common Migration Mistakes

Mistake	Symptom	Fix
Still using live_design!	Compile error	Replace with script_mod!
Using <Widget> syntax	Parse error	Use Widget{}
Using Key = Value	Property not applied	Use Key: value
Using (THEME_COLOR)	Unknown token	Use theme.color_*
Missing height: Fit	Container invisible (0px)	Add height: Fit
Using Live derive	Compile error	Use Script
Using before_apply	Method not found	Use on_before_apply
Using commas between props	Parse error	Remove commas

---

Best Practices for Migration

1. Start with examples - Study examples/counter and examples/todo for 2.0 patterns
2. Migrate one widget at a time - Don't try to convert everything at once
3. Check the old/ directory - Compare old vs new widget implementations
4. Test height: Fit - Most invisible UI is caused by missing height
5. Use theme variables - Replace all hardcoded theme colors with theme.*
6. Add new_batch: true - Any View with show_bg and text children needs it