Import & handoff

Which workflow fits?

Work from the project root for each workflow. Import is for code without Dwell configuration; handoff is for an existing Dwell project on your machine.

• Import analyzes existing applications and proposes a Dwell configuration.
• Handoff shows local prerequisites and blockers; it does not create a transfer package.
• Reinit repairs the association of a Dwell project after physically moving or renaming its directory.

Import existing code

Save your work in the repository. Analyze without changes first and review the proposal: detected roles, directories, versions, PHP, warnings and open questions.

dwell import --json

dwell import shows the preview again and asks for confirmation before writing in an interactive terminal. Accept only when it matches your project. Explicit role and directory arguments can help with unclear detection; the command reference lists all options.

dwell import

Managed detection

Dwell recognizes Symfony, Laravel, Shopware 6, TYPO3 and WordPress, plus React/Vite and Vue/Vite. It prefers version information from lockfiles. A detected managed role needs a supported version line; unsupported frameworks are not silently upgraded.

Custom fallback

Other PHP or JavaScript applications may be proposed as custom roles. Check the PHP backend webroot and frontend start command. You own the application, dependencies and compatibility; Dwell provides the local runtime within the custom contract.

Import creates Dwell configuration and local state around existing code. It moves no source files, adopts no foreign Docker, Compose or routing infrastructure and installs no application dependencies itself. Then run handoff, address blockers and start:

dwell handoff
dwell build
dwell up

Hand a project over

Share source, .dwell/dwell.json and dependency lockfiles through your repository. Keep local secrets, runtime files and databases out of Git. Transfer any required application data as a separate backup through an appropriate secure channel.

1. Clone the repository on the receiving machine and enter the project root.
2. Provide Node.js, npm and Docker with Linux containers; some frontends require a higher Node version.
3. Run dwell handoff and address reported blockers using their suggested next steps.
4. Supply local environment values and secrets, then run dwell build and dwell up.

dwell handoff

Handoff checks configuration, stack versions, role directories, local tools, Docker reachability and known host conflicts. For .env.example or .env.dist it checks declared keys in .env or .env.local; presence does not validate the values for your application. It copies no secrets, containers or VMs and does not guarantee successful application startup.

Moved the project directory?

After moving or renaming the whole project directory in the filesystem, enter its new location and run reinit. Preserve its .dwell configuration and persistent local state.

dwell reinit

Reinit updates registry and runtime associations. It moves no files itself and keeps the configured slug by default. Directory name, display name and host base do not automatically change together. A second existing clone with the same project identity can cause a collision; reinit is not a copying workflow.

Notes & limits

An existing Dwell project cannot be imported again. Nested role paths such as apps/web are unsupported; a single application can remain at the repository root. Use import --yes only for an unambiguous proposal: warnings and open questions block automatic application. Custom frontends need a valid start command for up. Check secrets and application data separately from the repository.

Next steps

The projects guide explains everyday starting and stopping. Use the stack guide for custom responsibilities and compatible versions.

Technical reference