Your frontend needs a new field from the API. The API needs an updated validation schema. In separate repositories, that small change can turn into several pull requests and a carefully ordered release.

A monorepo puts related applications and shared packages in one Git repository. You can review a feature across those boundaries in one place, keep tooling consistent, and reuse code without publishing every internal package to a registry.

The deployment question is straightforward: how do you give each app its own build and runtime while keeping access to the code it shares?

This guide walks through a small npm workspace and the Hostless settings that connect it to production.

What belongs in a monorepo?

A common layout separates deployable services from reusable libraries:

my-product/
├── apps/
│   ├── web/              # Frontend
│   ├── api/              # HTTP API
│   └── worker/           # Background jobs
├── packages/
│   └── shared/           # Types, validation, utilities
├── package.json
└── package-lock.json

Each app has its own package.json and build scripts. The repository root defines the workspace. Shared packages expose a clear public interface that the apps import.

A monorepo is useful when services evolve together or share substantial code. It also needs discipline: unclear dependencies, giant build commands, and packages that import each other's internals can make a single repository harder to maintain. Independent products with separate ownership may be easier to keep in separate repositories.

You do not need Nx or Turborepo to start. Add a task orchestrator when dependency ordering, caching, or build duration becomes a real problem.

1. Set up npm workspaces

At the repository root, define the workspace folders:

{
  "name": "my-product",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build:shared": "npm run build --workspace packages/shared",
    "build:api": "npm run build:shared && npm run build --workspace apps/api"
  }
}

Give every workspace a unique package name, such as @my-product/api and @my-product/shared. Declare shared packages as dependencies of the apps that import them. For npm workspaces, a matching version can link the local package:

{
  "name": "@my-product/api",
  "private": true,
  "dependencies": {
    "@my-product/shared": "1.0.0"
  },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "start": "node dist/index.js"
  }
}

This assumes packages/shared declares version 1.0.0 and exposes its compiled output, and that the API already has its TypeScript configuration and other dependencies. Adapt the names and scripts to your framework.

Run npm install from the root and commit the resulting package-lock.json. Then check a clean installation and build:

npm ci
npm run build:api

If the shared library emits JavaScript or declarations, build it before its consumers. A workspace links packages; it does not automatically decide their compilation order.

2. Choose a Hostless resource for each workload

Create a Hostless project and connect your Git repository. For repository authorization and the first deployment flow, see Deploy from GitHub to Hostless.

Use an App for an API or a frontend that runs a server. Use a Site for a frontend that produces static files. A background process belongs in a Worker, and scheduled work belongs in a Cron Job.

Point each code resource at the same repository and choose its deployment branch. Configure the resource for the folder and commands it needs. Keeping the API and frontend as separate resources lets you configure their environment variables, domains, and runtime requirements independently.

Sharing a repository does not mean every process should start in one container.

3. Set the working directory and build context

These settings answer different questions:

Setting Purpose API example
Working Directory Selects the app folder for automatic builds apps/api
Build Context Directory Controls which repository files the builder can access /
Pre-build Command Prepares dependencies or shared packages before an automatic build npm ci && npm run build:shared

An app with everything it needs inside apps/api can use that folder as its context. An app that needs the root lockfile and packages/shared needs a broader context. In our example, set it to / so those files are available.

You can edit these values in the dashboard. Existing apps expose them under Settings → General; creation forms also offer build configuration options. See the build configuration reference for the directory behavior.

For the API, use npm run build as the build command and npm start as the start command. Those scripts belong to apps/api/package.json. The pre-build command runs from the context directory, so our root-level build:shared script is available there.

4. Keep the API settings in version control

You can also describe the API build in a Hostless configuration file:

working_directory: apps/api
build_context_directory: /
pre_build_command: "npm ci && npm run build:shared"

build:
  system: auto
  command: "npm run build"

start_command: "npm start"

Commit this as hostless.api.yaml at the repository root and select that path in the API's Hostless file setting. Hostless defaults to reading hostless.yaml, so a custom filename must be configured explicitly.

Use a separate configuration path for another app with different settings. For example, a server-rendered frontend could use hostless.web.yaml with working_directory: apps/web and its own build and start scripts. This avoids accidentally applying the API configuration to both resources.

For a static frontend, select a Site and set its output directory to the folder your frontend build actually emits, such as dist for a typical Vite project. A static Site serves built files and does not need an application server start command.

The hostless.yaml reference documents the available fields and custom file locations.

5. Use Docker when you need explicit control

If your build needs operating-system packages, a particular toolchain, or a carefully chosen runtime image, put those steps in a Dockerfile.

Keep the repository root as the build context when the Dockerfile copies sibling packages. Docker COPY sources are relative to the build context, so a COPY of packages/shared requires that folder to be inside it. Check .dockerignore too: excluding the shared folder makes it unavailable even with the correct context.

For Docker builds, install dependencies and build packages inside the Dockerfile. Hostless's pre-build command is for automatic builds and is ignored for Docker builds. Test the image locally using the same context before deploying it.

6. Connect and verify the services

Add secrets and runtime configuration through Hostless environment settings. Keep database credentials and tokens out of Git. Configure the frontend to call the API's HTTPS address, and allow the frontend origin in the API's CORS settings where required.

Remember that many static frontend frameworks embed environment variables during the build. Changing an API URL in those settings usually requires rebuilding the frontend; it will not update an already generated JavaScript bundle.

For server processes, listen on the port expected by your Hostless configuration and bind to 0.0.0.0 so requests can reach the process.

After deploying, check the build logs, startup logs, and public URL. Exercise one request that crosses the frontend, API, and database. Then change a shared package and redeploy every consumer that needs the update. A shared source change only reaches a running service after that service is rebuilt and deployed.

When a monorepo build fails

A shared package cannot be found. Check that the app declares the dependency, the root workspace patterns include it, and the build context contains it.

The build cannot find package-lock.json. Confirm that the root lockfile is committed and the install command runs from the repository root.

An import points to a missing dist file. Build the shared package before the app and check that its package exports match the emitted files.

The wrong app starts. Check the working directory, package scripts, and selected Hostless configuration file. A root script that starts every workspace is usually the wrong start command for a single resource.

It works locally but fails on Hostless. Compare the Node version, environment variables, filename casing, and clean-install behavior. Local node_modules and uncommitted build output can hide missing dependencies.

Start with one app, get a clean deployment working, then add the next resource. With an explicit build context and clear package boundaries, you can keep related code together while giving each service the deployment it needs.

Open Hostless and connect your monorepo to get started.