Set Up Monorepo Support

A monolithic repository (monorepo) contains multiple projects or packages within a single repository. Vega Studio supports monorepo layouts through npm and Yarn workspaces. Yarn v2 layouts are preferred, but v1 is also supported except for nohoist.

With monorepo support, you can:

• Open monorepo packages
• Import Vega projects into a VS Code or Kiro workspace
• Manage multiple projects efficiently

A monorepo structure enables code sharing, centralizes dependency management, and reduces project setup steps.

The Vega SDK includes the npm package manager by default. If you prefer Yarn, see Set Up Yarn Workspace.

Prerequisites

• Set up Vega Studio

Turn on or off monorepo support

To turn monorepo support on or off, go to Settings > Vega > Features: Monorepo and select or clear the checkbox.

Modify monorepo behavior

1. Go to Settings > Vega > Features: Monorepo Synchronization.

2. Choose from these options:

   • Auto – Automatically detects and imports sub-packages in the background when you open or add a monorepo package to a VS Code workspace.
   • Ask for confirmation – Detects sub-packages, but asks for permission before importing.
   Note: Import can install npm dependencies and cause VS Code workspace to reload.

Understand the different workflows

When using monorepo layout packages, the workflows differ in these ways:

Opening and adding packages

• Open a workspace without a monorepo package – Identifies the package layout in the background without interfering with your workflow.
• Open a workspace with a monorepo package – Identifies the layout, enumerates sub-packages, detects Vega projects, and adds them to the workspace. This behavior depends on your monorepo synchronization setting. See Modify monorepo behavior.
• Add a monorepo package to a VS Code workspace – Functions the same as opening a workspace with a monorepo package.
• Add a Vega project to a monorepo – See instructions in Add Vega projects to a monorepo.

Building

• Build an entire monorepo – Uses the VS Code default build task.

  Vega Studio doesn't support auto-configuration of the build task. You must configure it. In VS Code, you can do one of the following:

  • Go to Terminal > Run Build Task.
  • Press Cmd+Shift+B on your keyboard.
  • Go to the command palette and enter Tasks: Run Build Task.

Viewing

• The VS Code Explorer view – Shows Vega projects inside the monorepo and as separate entries in the VS Code workspace.
• The Vega Studio view – Displays Vega projects as normal.
• Other workflows – Remain unchanged from non-monorepo workspaces.

Add Vega projects to a monorepo

1. Create a new Vega project from a template in the packages directory of your monorepo.

2. Update the dependency in your JavaScript app's package.json:

   // REPLACE
   "@prefix/module-name": "file:...../prefix-module-name-0.0.1.tgz"
   // WITH
   "@prefix/module-name": "*"
   

3. Add the node_modules path to metro.config.js:

   Copy code Copied to clipboard.

   const path = require('path');
      
   const config = {
     projectRoot: __dirname,
     watchFolders: [
       path.resolve(__dirname, '../../packages'),
       path.resolve(__dirname, '../../node_modules')
     ],
     resolver: {
       disableHierarchicalLookup: true,
       nodeModulesPaths: [
         path.resolve(__dirname, 'node_modules'),
         path.resolve(__dirname, '../../node_modules')
       ]
     }
   };
   

4. Remove unnecessary lock files and package artifacts (especially package-lock.json files when using Yarn).

5. For Yarn with corepack, specify the package manager in package.json:

   Copy code Copied to clipboard.

   "packageManager": "yarn@x.y.z"
   

Troubleshoot monorepo issues

If you encounter issues when working with a monorepo in Vega Studio, see Resolve Monorepo issues for solutions.

Next steps

• Build Your App
• Run Your App

Related topics

• Set Up Vega Studio
• Set Up Yarn Workspaces
• Resolve Monorepo Issues

---

Last updated: Feb 18, 2026