How to Use Hako with Monorepos

This guide shows how to use hako with monorepos to manage multiple workspace services in isolated environments.

Assumptions

• Project is a monorepo using workspaces (pnpm, yarn, npm, or bun).
• Workspace packages contain development scripts.

Steps

1. Prepare the root package.json Ensure the root package.json does not have a dev or start script. This triggers hako's monorepo fallback detection.

2. Configure workspace packages Ensure each workspace package you want hako to manage has a scripts.dev or scripts.start entry.

3. Initialize the environment Run the following command to create a new worktree. Hako auto-detects the workspaces and generates a multi-service hako.yml.

   hako new feature-branch --start

4. Verify detected services Check that all intended services are running and healthy.

   hako status feature-branch

5. View per-service logs Inspect the output of a specific workspace service.

   hako logs feature-branch web

Port allocation

Each detected service is assigned its own unique port variable based on the package name (e.g., PORT_WEB, PORT_API).

Manual adjustments

If auto-detection includes unwanted packages or misses services, edit the generated hako.yml to add or remove entries from the services section.

Fallback detection

If you are using Lerna without native package manager workspaces, hako reads the packages field in lerna.json as a fallback.

See also

• Auto-detection Reference for full detection rules and supported package managers.