Add a New Application to Your Makerkit Monorepo

Create additional applications in your Turborepo monorepo using git subtree to maintain updates from Makerkit while building separate products.

Add new applications to your Makerkit monorepo using git subtree to clone the apps/web template while maintaining the ability to pull updates from the Makerkit repository. This is useful for building multiple products (e.g., a main app and an admin dashboard) that share the same packages and infrastructure.

Add a Turborepo Application

Create a new application from the web template

1

Create the subtree branch

2

Add the new application

3

Configure the application

4

Keep it updated

When to Add a New Application

Add a new Turborepo application when:

  • Multiple products: You're building separate products that share authentication, billing, or UI components
  • Admin dashboard: You need a separate admin interface with different routing and permissions
  • API server: You want a dedicated API application separate from your main web app
  • Mobile companion: You're building a React Native or Expo app that shares business logic

Keep a single application when:

  • You only need one web application
  • Different features can live under different routes in apps/web
  • Separation isn't worth the complexity

Step 1: Create the Subtree Branch

First, create a branch that contains only the apps/web folder. This branch serves as the template for new applications.

git subtree split --prefix=apps/web --branch web-branch

This command:

  1. Extracts the history of apps/web into a new branch
  2. Creates web-branch containing only the apps/web contents
  3. Preserves commit history for that folder

Step 2: Add the New Application

Create your new application by pulling from the subtree branch.

For example, to create a pdf-chat application:

git subtree add --prefix=apps/pdf-chat origin web-branch --squash

This command:

  1. Creates apps/pdf-chat with the same structure as apps/web
  2. Squashes the history into a single commit (cleaner git log)
  3. Sets up tracking for future updates

Verify the Application

ls apps/pdf-chat

You should see the same structure as apps/web:

apps/pdf-chat/
├── app/
├── components/
├── config/
├── lib/
├── supabase/
├── next.config.mjs
├── package.json
└── ...

Step 3: Configure the New Application

Update package.json

Change the package name and any app-specific settings:

apps/pdf-chat/package.json

{
  "name": "pdf-chat",
  "version": "0.0.1",
  "scripts": {
    "dev": "next dev --port 3001",
    "build": "next build",
    "start": "next start --port 3001"
  }
}

Update Environment Variables

Create a separate .env.local for the new application:

apps/pdf-chat/.env.local

NEXT_PUBLIC_SITE_URL=http://localhost:3001
NEXT_PUBLIC_APP_NAME="PDF Chat"
# ... other environment variables

Update Supabase Configuration (if separate)

If the application needs its own database, update apps/pdf-chat/supabase/config.toml with unique ports and project settings.

Add Turbo Configuration

Update the root turbo.json to include your new application:

turbo.json

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "pdf-chat#dev": {
      "dependsOn": ["^build"],
      "persistent": true
    }
  }
}

Run the New Application

# Run just the new app
pnpm --filter pdf-chat dev
# Run all apps in parallel
pnpm dev

Step 4: Pulling Updates

When Makerkit releases updates, follow these steps to sync them to your new application.

Pull Upstream Changes

First, pull the latest changes from Makerkit:

git pull upstream main

Update the Subtree Branch

Re-extract the apps/web folder into the subtree branch:

git subtree split --prefix=apps/web --branch web-branch

Push the Branch

Push the updated branch to your repository:

git push origin web-branch

Pull Into Your Application

Finally, pull the updates into your new application:

git subtree pull --prefix=apps/pdf-chat origin web-branch --squash

Resolve Conflicts

If you've modified files that were also changed upstream, you'll need to resolve conflicts:

# After conflicts appear
git status  # See conflicted files
# Edit files to resolve conflicts
git add .
git commit -m "Merge upstream changes into pdf-chat"

Update Workflow Summary

# 1. Get latest from Makerkit
git pull upstream main
# 2. Update the template branch
git subtree split --prefix=apps/web --branch web-branch
git push origin web-branch
# 3. Pull into each additional app
git subtree pull --prefix=apps/pdf-chat origin web-branch --squash
git subtree pull --prefix=apps/admin origin web-branch --squash

Troubleshooting

"fatal: refusing to merge unrelated histories"

Add the --squash flag to ignore history differences:

git subtree pull --prefix=apps/pdf-chat origin web-branch --squash

Subtree branch doesn't exist on remote

Push it first:

git push origin web-branch

Application won't start (port conflict)

Update the port in package.json:

{
  "scripts": {
    "dev": "next dev --port 3001"
  }
}

Shared packages not resolving

Ensure the new app's package.json includes the workspace dependencies:

{
  "dependencies": {
    "@kit/ui": "workspace:*",
    "@kit/supabase": "workspace:*"
  }
}

Then run pnpm install from the repository root.