Custom Builds & Application Packaging

Framework M and its standard UI (the Desk) are distributed as pre-bundled Python wheels via PyPI/GitLab. You do NOT need to rebuild the framework's core frontend unless you are developing the framework itself.

1. Official Core Packages

Always use the standard package names when defining dependencies or building Docker images:

Ecosystem	Package Name	Description
Python	framework-m	The meta-package (installs core, standard, and CLI).
	framework-m-core	The kernel, DocType engine, and protocols.
	framework-m-standard	Default adapters and the bundled Desk assets.
	framework-m-studio	Development tools and UI-based schema builders.
Node.js	@framework-m/ui	Core UI component library (shared with plugins).
	@framework-m/desk	The Desk application shell and system modules.
	@framework-m/plugin-sdk	Tools for building custom frontend plugins.
	@framework-m/vite-plugin	Vite integration for Module Federation.

Shared UI Foundation

Framework M uses a Shared Dependency Model. Custom applications and the core Desk both build upon @framework-m/ui and @framework-m/desk. This ensures that custom plugins are visually consistent and can reuse existing Desk components and patterns.

2. Packaging Your Application

When building a custom application on top of Framework M, you package your own code as a wheel that contains its own assets, extending the pre-bundled framework.

Step 1: Python Logic & DocTypes

Define your DocTypes in your own Python package (e.g., my_app). Use your build system (hatch, setuptools) to include static assets.

# my_app/pyproject.toml
[tool.hatch.build.targets.wheel.force-include]
"src/my_app/static" = "my_app/static"

Step 2: Custom Frontend Apps (Optional)

Frontend apps (plugins) add new UI components to the already running Desk Shell.

• Shell Role: @framework-m/desk provides the application shell, including the desktop, core navigation, and the sidebar.
• Frontend App Role: Your custom app provides the views, fields, and dashboard components that are federated into the shell at runtime.

Build your frontend apps using the @framework-m/plugin-sdk. Your build will share dependencies with the core packages to keep the final bundle lean.

# In your app's frontend directory
pnpm install # Shared foundation (@framework-m/ui, @framework-m/desk) is linked
pnpm build   # Assets generated in src/my_app/static

Step 3: Deployment Dockerfile (Multi-Stage)

In production, use a multi-stage build to compile your custom frontend assets and then install your application into a lean Python image alongside Framework M.

# Stage 1: Build Custom Frontend
FROM node:20-slim AS frontend-builder
WORKDIR /build
COPY . .
RUN corepack enable && pnpm install
# Build your app's frontend (output to src/my_app/static)
RUN pnpm -F my_app_frontend build

# Stage 2: Production Image
FROM python:3.12-slim
WORKDIR /app

# 1. Install Framework M (pre-bundled with Desk/UI assets)
RUN uv pip install framework-m

# 2. Install your custom app
# Copy everything including the built assets from Stage 1
COPY --from=frontend-builder /build /tmp/my_app
RUN uv pip install /tmp/my_app

# 3. Start the application
CMD ["m", "start"]

3. Best Practices

1. Dependency Alignment: Ensure your app's frontend dependencies match the versions used by the installed @framework-m/desk to avoid runtime collisions.
2. Wheel-Centric Distribution: All production deployments should be centered around pip install. If you have custom UI, bundle the built JS/CSS into your Wheel using package_data.
3. Discovery: Framework M scans the site-packages of all installed modules at startup to discover DocTypes, API routes, and static assets.