Monorepo projects

This guide covers using Flow when your AdonisJS application lives inside a monorepo. You will learn how to:

• Understand where Flow installs when your app is in a subdirectory
• Add the Flow package and run the installer
• Launch your coding agent from the right directory
• Override the workspace root when Flow needs help finding it

Overview

A monorepo keeps several packages in one repository, with your AdonisJS app in a subdirectory such as apps/backend alongside a frontend or shared packages. Flow supports this layout for a single AdonisJS app per repository.

In a monorepo, Flow works across two separate directories.

• Your app lives in its own directory, where adonisrc.ts and package.json sit and where node ace runs.
• Your coding agent, on the other hand, works from the repository root, the workspace root, where it looks for its skills and context file.

Flow installs the agent-facing files at the workspace root so your agent finds them, while still reading your application from its subdirectory. You do not wire any of this up by hand.

Installing in a monorepo

Because the two directories differ, installation happens in two places. You add the package through your package manager at the workspace root, then run Flow's commands from your app.

Add the package

In a standalone project, node ace add installs the package and configures it in one step. In a monorepo your package manager owns the workspace's dependencies, so add @adonisplus/flow to your app with the package manager instead.

npm install @adonisplus/flow --workspace apps/backend

pnpm --filter ./apps/backend add @adonisplus/flow

yarn workspace backend add @adonisplus/flow

cd apps/backend && bun add @adonisplus/flow

Replace apps/backend with your app's location. yarn targets the app by its package.json name, and bun adds from inside the app directory.

Run the installer

From your app directory, configure the package and run the installer.

cd apps/backend

node ace configure @adonisplus/flow
node ace flow:install

When you run flow:install, it prompts you to confirm the workspace root before writing anything.

> Detected a monorepo. Harness will be installed at: › "/Users/you/code/my-monorepo"

Running your coding agent

Launch your coding agent from the workspace root, not from your app directory. Its skills, its context file, and the .flow/ directory all live there.

Your agent already knows your app lives in a subdirectory. It writes application files into apps/backend and runs node ace commands from there on its own, so you never have to point it back to the app.

Overriding the workspace root

Flow finds the workspace root from a pnpm-workspace.yaml file or a workspaces field in a package.json above your app. When your layout uses neither, or Flow picks the wrong directory, you have two ways to correct it.

For a single command, type the right path at the flow:install or flow:uninstall prompt. For every command at once, set the FLOW_WORKSPACE_ROOT environment variable in your shell profile so install, uninstall, and the Flow Dashboard all resolve the same root.

FLOW_WORKSPACE_ROOT=/Users/you/code/my-monorepo node ace serve --hmr

Limitations

Flow supports one AdonisJS application per monorepo. If your repository holds several, install Flow for the one you want the harness to cover.

If you run more than one AdonisJS app in a single monorepo, we would like to hear from you. Tell us about your setup on our Discord, so we can learn how you work and support the layout properly.

Next steps

• Read the Installation guide for the full set of installer prompts and what each one writes.
• Read the guide for the agent you use, such as Claude Code or Cursor.
• Read Spec-driven development to start using the workflow.