Export into an existing React or Next.js app

Integrate Misaki Studio output by giving generated files a replaceable boundary and keeping application-specific routing, providers, business logic, tests, and adapters outside it. Inspect one Component first, prove it in a clean branch, then adopt the complete project output it depends on.

Coverage: UI + MCP for inspection, target configuration, and local-folder export. Desktop required for the local write. Integration and build changes happen in your application repository.

Do not start by overwriting src

First export into a dedicated, reviewable location such as:

app/
├── src/
│   ├── generated/misaki/   ← replaceable output
│   ├── integration/        ← handwritten adapters
│   └── app-or-pages/       ← application-owned routing/composition
├── public/misaki/          ← reviewed generated assets
├── tests/                  ← consumer-owned tests
└── package.json            ← consumer-owned dependencies/scripts

A boilerplate can use a broader generated path because its shell was designed around that boundary. In an established application, a dedicated namespace makes repeated export and diff review safer.

Inspect the Component contract

Before writing files, run code preview or MCP export-code for the target Component/Page. Record:

• exported Component, Props, DefaultProps, Variants, and Children symbols that actually exist;

• root inputs such as properties, variant, children, className, style, and divProps;

• generated .module.scss imports;

• misaki-studio-internal and other package imports;

• other generated Components, design-system modules, assets, APIs, storage, Content, database, environment, Document, or Script dependencies;

• client-module and routing assumptions.

One TSX file may not be portable by itself. Whole-project export preserves the paths between generated modules and assets.

Prepare the application

1. Create a branch or other recoverable snapshot.

2. Confirm the application's React/Next.js, TypeScript, Sass/CSS-module, and package-manager setup.

3. Choose generated source and asset directories that do not contain handwritten files.

4. Install only dependencies proven by the current generated imports, using compatible versions.

5. Add a handwritten adapter that imports the generated Component and translates application data into its public contract.

6. Keep routing and provider decisions in application-owned code unless the generated Page is intentionally taking over that route.

Generated visual modules can contain "use client" because their behavior uses hooks or browser runtime helpers. In a Next.js application, compose that boundary intentionally rather than removing the directive from generated code.

Configure and run a local export

Configure one local-folder target in settings/export:

REACT SRC PATH  → /absolute/path/to/app/src/generated/misaki
ASSET PATH      → /absolute/path/to/app/public/misaki
NODEJS SRC PATH → empty

Use a backend path only after separately choosing and validating the generated backend workflow.

Then ask an agent:

In the selected Website project, read settings/export and return a redacted list of local targets. Verify that the approved target points only to <generated source dir> and <asset dir>, with no backend path. Search the destination for handwritten markers and show the pre-export Git status. If the target and boundary match exactly, run the normal export-code-to-folder. Report every target result and the resulting diff; do not edit generated files, install dependencies, commit, push, publish, or deploy.

The folder operation writes the whole project to every configured local target. Remove or verify obsolete targets before running it. One target can succeed even if another fails.

Add an adapter, not patches to generated files

Application-owned code should translate from your domain into the generated contract:

import * as StatusBadge from "../generated/misaki/components/atoms/status-badge";

export function OrderStatus({ status }: { status: "open" | "closed" }) {
  return (
    <StatusBadge.Component
      properties={{ label: status === "open" ? "Open" : "Closed" }}
      variant={[status]}
    />
  );
}

Use the exact names and types from the current generated module. The example shows the boundary, not a guaranteed contract for a particular Component.

Put analytics, application routing, server calls, feature flags, tests, and framework adapters in handwritten files. If the generator cannot express required behavior, either add a supported project feature or keep that behavior outside the generated tree.

Verify in the real consumer

1. Review every generated diff, including unexpected unrelated files and stale files that export did not remove.

2. Run the application's dependency install from its lockfile policy.

3. Run TypeScript, linting, tests, and a production build.

4. Exercise the adapter with default and meaningful props/variants/children.

5. Test responsive Components inside their real containers.

6. Verify assets, routes, themes, API/storage/data behavior, animation, and accessibility.

7. Re-export once more and confirm handwritten integration remains untouched.

Misaki diagnostics are helpful but lossy. Only the application's own build proves compatibility with its framework and dependencies.

Re-export and recover

Follow Re-export safely every time. Generated headers mean complete replacement is allowed; Script files are authored in Misaki but their destination copies are still refreshed from the project.

If an export is wrong, recover from the application repository's uncommitted diff or reviewed revert. Misaki Studio undo changes project files; it does not restore an external folder.

Current limits

• The exporter does not merge arbitrary handwritten changes inside generated files.

• It does not generally remove stale destination files after a project rename/deletion.

• The application must supply compatible packages, build configuration, routing, runtime services, and deployment.

• Current authentication/database/backend limitations still apply to generated consumers.

• Existing-app integration needs runtime verification against representative current React and Next.js fixtures before this draft is approved.