Multi-Project Sharing & Path Aliases

Overview

As Aircada workspaces scale, developers frequently need to share business logic, custom 3D math transformations, telemetry schemas, and React UI components across multiple distinct projects (e.g. parallel configurators, variations, or micro-plugins) without copy-pasting code or maintaining private npm registries.

The Aircada CLI provides native support for Path Aliasing and Multi-Root Shared Watchers via air.config.json, allowing multiple projects to link to one or more shared TypeScript directories seamlessly.

1. Project Configuration (air.config.json)

Each consuming project declares its external shared dependencies via two properties in air.config.json:

{
  "appType": "PROJECT",
  "appId": "bhVYexL2iln0jhAS",
  "pluginType": "APPLICATION",
  "projectId": "SXOCDzYBbIKG9W3k",
  "name": "Project Alpha",
  "sharedPaths": ["../shared-logic/src"],
  "aliases": {
    "@shared": "../shared-logic/src"
  }
}

- sharedPaths [String[]]: Relative paths from the project root to shared source directories. Used by the dev watcher to monitor file changes and by the Tailwind compiler to scan for utility classes.

- aliases [Record<string, string>]: Path alias mappings (e.g. @shared -> ../shared-logic/src). Passed directly to the bundler for compile-time resolution.

2. TypeScript Path Mapping (tsconfig.json)

To enable full IDE autocomplete, type-checking, and jump-to-definition across shared files, configure tsconfig.json in each consuming project:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "jsx": "react",
    "baseUrl": ".",
    "rootDir": ".",
    "paths": {
      "@shared/*": ["../shared-logic/src/*"],
      "@shared": ["../shared-logic/src/index"]
    },
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": [
    "src/**/*",
    "scripts/testing/**/*"
  ]
}

> Note on rootDir: Avoid setting rootDir: './src'. Setting rootDir: '.' (or omitting it) allows TypeScript to resolve out-of-tree files in shared directories without compiler errors.

3. Tailwind CSS v4 Integration

In Tailwind CSS v4, the PostCSS compiler scans project files for utility class names. To prevent Tailwind from purging classes used in external shared React components:

1. Automatic Injection: The CLI bundler automatically inspects sharedPaths and dynamically prepends @source '<absSharedPath>'; to the CSS input stream during PostCSS compilation.

2. Explicit Declaration: Developers can also manually write @source '../../shared-logic/src'; inside their project's src/index.css.

4. Dev Server Multi-Root Watcher (air dev)

When running in development mode (air dev), the dev server initializes a multi-root Chokidar file watcher:

- Simultaneously monitors project/src/ and all resolved paths in config.sharedPaths.

- Any file modification in a shared folder triggers a debounced (50ms) in-memory rebuild and broadcasts a code-update WebSocket payload to all connected Engine Studio sessions without file-locking conflicts.

5. Architectural Best Practices

- Passive Building Blocks: Shared directories should serve as passive libraries of reusable building blocks (classes, math utilities, schemas, React components, and abstract base classes).

- Local Auto-Registration Boundary: The CLI scanner intentionally scans only the local project/src/ directory to prevent auto-registration pollution.

- Explicit System Opt-In: To activate a shared system in a specific project, create a one-line re-export file in that project's src/systems/ (e.g. export { SharedTelemetrySystem as TelemetrySystem } from '@shared/systems/SharedTelemetrySystem';).