🎉 The Architech v1.0 is now available. Read more →
v2
Marketplace Documentation
Path Keys System

Path Keys System

Path keys provide semantic names for paths, making blueprints marketplace-agnostic and easier to maintain.

Overview

Path keys are semantic identifiers for paths:

// Instead of hardcoding
const path = 'apps/web/src/';
 
// Use semantic key
const path = paths['apps.web.src'];

Benefits:

  • Marketplace-agnostic blueprints
  • Easy to change structure
  • Type-safe path resolution

Structure

Path keys are defined in path-keys.json:

{
  "version": "2.0.0",
  "marketplace": "saas",
  "pathKeys": [
    {
      "key": "apps.web.root",
      "description": "Web app root directory",
      "required": false,
      "structure": "both",
      "computed": true,
      "group": "web-app"
    }
  ]
}

Path Key Fields

key

The semantic identifier:

{
  "key": "apps.web.root"
}

Usage: paths['apps.web.root'] → 'apps/web/'

description

Human-readable description:

{
  "description": "Web app root directory"
}

required

Whether the path key is required:

{
  "required": true
}

Note: Required keys must be resolved or generation fails.

structure

Which project structures this key applies to:

{
  "structure": "both"  // "monorepo", "single-app", or "both"
}

computed

Whether the path is computed from genome:

{
  "computed": true
}

Computed paths: Generated from genome (e.g., apps/web/ from app definition)
Non-computed paths: Use defaultValue

defaultValue

Default value if not computed:

{
  "computed": false,
  "defaultValue": "./"
}

group

Grouping category:

{
  "group": "web-app"
}

Groups: workspace, web-app, mobile-app, api-app, packages

Semantic Path Keys

Some path keys are "semantic" - they expand to multiple paths:

{
  "key": "apps.{appType}.src",
  "semantic": true,
  "resolveToApps": "all"
}

Expansion:

  • apps.web.src → apps/web/src/
  • apps.mobile.src → apps/mobile/src/
  • apps.api.src → apps/api/src/

Dynamic Path Keys

Path keys can use variables:

{
  "key": "packages.{packageName}.root",
  "variables": ["packageName"]
}

Usage:

paths['packages.auth.root']  // packages/auth/
paths['packages.ui.root']    // packages/ui/

Path Resolution

During Framework Bootstrap

Paths resolve relative to VFS root:

// VFS root: /project/apps/web
// Path resolution
if (vfsRoot === appDirectory) {
  paths['apps.web.root'] = './';  // Relative to VFS root
}

Why? Prevents nested directories.

During Module Execution

Paths resolve from project root:

// Project root: /project
// Path resolution
paths['apps.web.root'] = 'apps/web/';  // From project root
paths['packages.auth.root'] = 'packages/auth/';

Example

Path Keys

{
  "pathKeys": [
    {
      "key": "workspace.root",
      "defaultValue": "./",
      "computed": false
    },
    {
      "key": "apps.web.root",
      "computed": true
    },
    {
      "key": "apps.web.src",
      "computed": true
    },
    {
      "key": "packages.auth.root",
      "computed": true
    }
  ]
}

Generated Paths

{
  'workspace.root': './',
  'apps.web.root': 'apps/web/',
  'apps.web.src': 'apps/web/src/',
  'packages.auth.root': 'packages/auth/'
}

Usage in Blueprints

// Blueprint action
{
  type: 'CREATE_FILE',
  path: '<%= paths["apps.web.src"] %>/app.tsx',
  content: '...'
}

Result: File created at apps/web/src/app.tsx

Related

Recipe BooksManifest