Skip to main content

Co-coding with Framework M

"Co-coding" is the process of working on an application project and the Framework M source code simultaneously. This is the recommended workflow when you need to fix a bug in the framework or build a new framework feature that is required by your specific project—whether it's a multi-tenant business suite, an Electron-embedded desktop app, or an IoT orchestrator.

This guide shows you how to use the m dev-link command to create a "Zero-Touch" live link between your repos.

The Goal​

You want to make changes to the Framework M source code and have them reflected instantly in your application without modifying lockfiles or publishing packages.

Prerequisites​

  • A local clone of the Framework M repository.
  • An application workspace (e.g., tenant-registry or business-m).
  • framework-m-studio installed in your application's virtual environment.

Navigate to your application's root directory and run the dev-link command, pointing it to your local framework source:

m dev-link --path=/path/to/your/local/framework-m

What happens?​

  • Python: All framework libraries (core, standard, etc.) are installed into your app's virtual environment in editable mode (-e).
  • JavaScript: All @framework-m/* packages in your app's node_modules are replaced with symlinks pointing to the framework source.

Step 2: The Co-coding Workflow​

Once linked, your application is a "live window" into the framework.

Editing Python / CLI code​

  1. Open a file in framework-m/libs/core and make a change.
  2. Run any m command in your application repo.
  3. The change is reflected immediately.

Editing Frontend / UI code​

  1. Open a component in framework-m/libs/ui.
  2. Keep your application's dev server running (m dev or pnpm dev).
  3. The bundler (Vite) will notice the change through the symlink and trigger a Hot Module Replacement (HMR).

When you are finished co-coding and want to return to using the official released versions of the framework:

  • For Python: Run uv sync.
  • For JavaScript: Run pnpm install --force.

These commands will wipe the local links and restore the versions specified in your lockfiles.

Configuration​

You can customize which packages are linked using m.toml or environment variables.

Using m.toml​

Add a [dev-link] section to your project's m.toml:

[dev-link]
# Only link specific packages
include = ["framework-m-core", "ui"]

# Explicitly exclude packages (overrides include)
exclude = ["framework-mx-mongo", "studio"]

Using Environment Variables​

Environment variables take precedence over m.toml:

  • FRAMEWORK_M_LINK_INCLUDE: Comma-separated list of packages to include.
  • FRAMEWORK_M_LINK_EXCLUDE: Comma-separated list of packages to exclude.

Default Exclusions​

By default, framework-mx-mongo is excluded as it is considered a showcase extension rather than a core dependency.

Troubleshooting​

Windows Permissions​

On Windows, creating symlinks requires Developer Mode to be enabled. If you cannot enable it, m dev-link will automatically attempt to create Directory Junctions, which provide the same functionality without requiring Administrator rights.

uv run vs Direct Execution​

Avoid using standard uv run while co-coding, as it may attempt to "sync" your environment and remove your editable links. Instead, use direct commands (e.g., m migrate sync) or use the --active flag: uv run --active m ....