Decentraland Creator Hub Monorepo

🏗️ Project Structure
🚀 Quick Start
- Prerequisites
- Initial Setup
📋 Makefile Commands
🔧 Package Scripts
🔄 CI/CD Workflow
🏗️ Architecture
🧪 Testing
🚀 Development Workflow
📦 Publishing
🔧 Troubleshooting
- Common Issues
- Getting Help
🤝 Contributing
📚 Additional Resources
📄 License

This monorepo contains the Decentraland Creator Hub ecosystem, consisting of three main packages:

@dcl/asset-packs - Curated collections of 3D assets and Smart Items for Decentraland scenes
@dcl/inspector - A web-based 3D scene inspector for Decentraland
creator-hub - An Electron-based desktop application for creating and managing Decentraland scenes

🏗️ Project Structure

creator-hub/
├── packages/
│   ├── asset-packs/         # Asset packs and Smart Items
│   │   ├── packs/          # Asset pack definitions
│   │   ├── src/            # Runtime library
│   │   ├── scripts/        # Build and upload scripts
│   │   └── bin/            # Built SDK7 runtime
│   ├── inspector/           # Web-based 3D inspector
│   │   ├── src/            # Source code
│   │   ├── public/         # Built assets
│   │   └── test/           # Tests
│   └── creator-hub/         # Electron desktop application
│       ├── main/           # Main Electron process
│       ├── preload/        # Preload scripts
│       ├── renderer/       # React frontend
│       ├── shared/         # Shared utilities
│       ├── devtools-frontend/ # DevTools frontend (git submodule)
│       └── e2e/            # End-to-end tests
├── .github/workflows/       # CI/CD workflows
├── Makefile                # Build and development commands
└── package.json           # Root package configuration

🚀 Quick Start

Prerequisites

Before starting, ensure you have the following installed:

Node.js 22.x or higher (Download)
npm (comes with Node.js, preferred over yarn)
Git (Download)
Docker (optional, required for local asset-packs content server development)

Initial Setup

Clone the repository with submodules:

git clone --recurse-submodules https://github.com/decentraland/creator-hub.git
cd creator-hub

If you already cloned without submodules, initialize them:

git submodule update --init --recursive

Install dependencies and initialize the project:
```
make init
```
This command will:
- Install all dependencies for the monorepo and sub-packages
- Download and install Protocol Buffers compiler
- Initialize git submodules (devtools-frontend)
- Generate TypeScript definitions from .proto files
- Build all packages, including the Bevy renderer engine bundle and the Bevy editor-agent scene (see below) — the first make init is a bit slower because it also installs + builds packages/inspector/agents/bevy, which is a separate SDK7 project with its own node_modules

Testing the Bevy renderer

The inspector can render a scene with the Bevy engine as an alternative to the default Babylon renderer. It ships in the app after a normal make init / make build — no extra steps to set it up. To try it:

Open a scene in the Creator Hub.
Go to Settings → Editor → Scene renderer and choose Bevy.
The editor reloads and renders the scene in the Bevy engine.

Notes for reviewers:

Switching back to Babylon in the same setting restores the default renderer.
Bevy is wired end to end: the scene renders, inspector edits forward into the engine, viewport pick works, the translate / rotate / scale gizmos work, and drag-dropped assets place under the cursor, and a free-fly editor camera (toggle in the toolbar / backtick) supports focus-on-entity (F / double-click) and reset (Space). Known gaps (expected, not bugs — Bevy feature parity is in progress): the scene-metrics panel and minimap, animator clip dropdowns, and 3D spawn-point handles. Pick may select a model's collider rather than its visible mesh on scenes that split the two.
If you change any code under packages/inspector (including the Bevy agent), rerun make build-inspector — the app serves a prebuilt inspector bundle, so running the Creator Hub in watch mode (cd packages/creator-hub && npm run start) does not hot-reload inspector changes.

📋 Makefile Commands

The project uses a Makefile to manage common development tasks:

Setup Commands

Command	Description
`make install`	Install dependencies for all packages
`make install-protoc`	Download and install Protocol Buffers compiler
`make init-submodules`	Initialize git submodules (devtools-frontend)
`make protoc`	Generate TypeScript definitions from `.proto` files
`make init`	Complete project initialization (clean + install + protoc + build)

Build Commands

Command	Description
`make build`	Build all packages (asset-packs, inspector, creator-hub)
`make build-asset-packs`	Build only the asset-packs package
`make build-inspector`	Build only the inspector package
`make build-creator-hub`	Build only the creator-hub package
`make validate-asset-packs`	Validate asset-packs assets
`make upload-asset-packs`	Upload asset-packs to content server

Development Commands

Command	Description
`make lint`	Run ESLint across all packages
`make lint-fix`	Fix ESLint issues automatically
`make format`	Format code with Prettier
`make typecheck`	Run TypeScript type checking
`make test`	Run unit tests for all packages
`make test-e2e`	Run end-to-end tests for all packages

Dependency Management

Command	Description
`make sync-deps`	Synchronize dependencies across packages using syncpack
`make lint-packages`	Check for dependency mismatches

Cleanup Commands

Command	Description
`make clean`	Remove build artifacts and dist folders
`make deep-clean`	Remove all node_modules and generated files

🔧 Package Scripts

Asset Packs Scripts

cd packages/asset-packs

# Development
npm run start          # Start SDK7 dev server (port 8001) and watch for changes

# Building
npm run build          # Build all (SDK7 scene, library, catalog)
npm run build:js       # Build SDK7 scene (bin/index.js)
npm run build:lib      # Build TypeScript library
npm run build:catalog  # Generate catalog.json

# Asset Management
npm run validate       # Validate all assets
npm run upload         # Upload assets to content server
npm run download       # Download assets from content server

# Type checking
npm run typecheck      # Type check the library

Inspector Scripts

cd packages/inspector

# Development
npm run start          # Start in watch mode

# Building
npm run build          # Build the inspector

# Testing
npm run test           # Run unit tests
npm run test:e2e       # Run end-to-end tests

# Type checking
npm run typecheck      # Type check the inspector

Creator Hub Scripts

cd packages/creator-hub

# Development
npm run start          # Start in watch mode

# Building
npm run build          # Build all parts (main, preload, renderer)
npm run build:main     # Build main process
npm run build:preload  # Build preload scripts
npm run build:renderer # Build renderer (React app)

# Testing
npm run test           # Run all tests
npm run test:e2e       # Run end-to-end tests
npm run test:unit      # Run unit tests

# Type checking
npm run typecheck      # Type check all parts

🔄 CI/CD Workflow

The project uses GitHub Actions with a sophisticated CI/CD pipeline:

Main CI Workflow (`ci.yml`)

The main workflow orchestrates all CI processes and runs on:

Push to main branch
Pull requests

Workflow Steps:

Lint - Code formatting and linting
Typechecking - TypeScript type checking
Tests - Unit and end-to-end tests
Drop Pre-release - Create pre-release artifacts
Asset Packs Build - Build, validate, and publish asset-packs package
Inspector Build - Build and publish inspector package (depends on asset-packs)
Creator Hub Build - Build and publish creator hub

Test Workflow (`tests.yml`)

Runs comprehensive testing:

Unit Tests - Runs on Ubuntu with Node.js 22
E2E Tests - Runs on macOS and Windows with Playwright
Cross-platform Testing - Tests both packages

Asset Packs Workflow (`asset-packs.yml`)

Handles asset-packs package deployment:

Validates all assets
Builds the asset-packs package
Publishes to npm (main branch only)
Uploads assets to S3 CDN (dev and prod environments)
Creates GitHub releases with release notes

Inspector Workflow (`inspector.yml`)

Handles inspector package deployment:

Builds the inspector package (depends on asset-packs)
Publishes to S3 for branch previews
Deploys to GitHub Pages
Publishes to npm (main branch only)
Creates GitHub releases with release notes

Creator Hub Workflow (`creator-hub.yml`)

Handles desktop application builds:

Multi-platform Builds - macOS and Windows
Code Signing - Automatic code signing for both platforms
Notarization - macOS notarization
Artifact Distribution - Uploads to S3 and GitHub releases
PR Testing - Provides download links for PR testing

🏗️ Architecture

Monorepo Structure

The project uses npm workspaces to manage the monorepo:

{
  "workspaces": ["packages/*"]
}

Dependency Management

syncpack is used to synchronize dependencies across packages
Shared dependencies are defined in the root package.json
Package-specific dependencies are in each package's package.json
The @dcl/inspector dependency is managed specially in .syncpackrc.json

Protocol Buffers

The Inspector package uses Protocol Buffers for data layer communication:

.proto files are in packages/inspector/src/lib/data-layer/proto/
Generated TypeScript files are in packages/inspector/src/lib/data-layer/proto/gen/
Use make protoc to regenerate after .proto changes

For a detailed guide to how the three packages connect and communicate at runtime, see docs/architecture.md.

🧪 Testing

Unit Tests

Creator Hub: Uses Vitest for main, preload, renderer, and shared tests
Inspector: Uses Vitest for unit tests
Run with make test or npm run test in individual packages

End-to-End Tests

Creator Hub: Uses Playwright for Electron app testing
Inspector: Uses Playwright for web app testing
Run with make test-e2e
Tests automatically build the applications before running

Test Structure

packages/creator-hub/e2e/          # Creator Hub E2E tests
packages/inspector/test/e2e/       # Inspector E2E tests

🚀 Development Workflow

Typical Development Flow

Start Development:

make init                    # Initial setup
cd packages/creator-hub
npm run start               # Start creator hub in watch mode

In another terminal:

cd packages/inspector
npm run start               # Start inspector in watch mode

Before Committing:
- Lint, format & typecheck will be run automatically

Local Development with Asset Packs

To develop with local asset-packs integration (for testing new assets or Smart Items):

Initial setup:
```
make init  # Sets up entire monorepo
```

Start asset-packs SDK7 dev server:

cd packages/asset-packs
npm run start  # Starts SDK7 server on port 8001

In another terminal, start docker content server:

cd packages/asset-packs
docker-compose up  # Starts content server on port 9000

In another terminal, upload assets to local content server:

cd packages/asset-packs
npm run upload  # Uploads assets to http://localhost:9000

In another terminal, start inspector dev server:

cd packages/inspector
npm start  # Starts on port 8000

In another terminal, start Creator Hub:

cd packages/creator-hub
cp .env.example .env  # First time only
# Edit .env and update VITE_ASSET_PACKS_JS_PATH with your absolute path
npm start  # Starts on default port

Configure environment variables in packages/creator-hub/.env:

VITE_INSPECTOR_PORT=8000
VITE_ASSET_PACKS_CONTENT_URL=http://localhost:9000/asset-packs
VITE_ASSET_PACKS_JS_PORT=8001
VITE_ASSET_PACKS_JS_PATH=/absolute/path/to/creators-hub/packages/asset-packs/bin/index.js

Now Creator Hub will use:

Local inspector on port 8000
Local asset-packs SDK7 runtime on port 8001
Local content server for assets on port 9000

For inspector-only development with local asset-packs, see Inspector README.

Launch Build Locally

To launch build locally on macOS, you may need to remove quarantine attributes:

xattr -c /Applications/Decentraland\ Creator\ Hub.app/

Note: This command is necessary on macOS to bypass Gatekeeper when running locally built versions. This issue doesn't occur with officially signed releases.

Code Quality

ESLint - Code linting with custom rules
Prettier - Code formatting
TypeScript - Static type checking
syncpack - Dependency synchronization

📦 Publishing

Asset Packs Package

Automatically published to npm on main branch
Assets uploaded to prod S3 CDN on main branch
PR builds available for testing (npm package only)
Dev CDN uploads: Triggered manually by org members commenting /upload-assets on PRs
GitHub Releases: Always marked as pre-releases to avoid confusion with electron-updater

Inspector Package

Automatically published to npm on main branch
PR builds available for testing
GitHub Pages deployment for web previews
GitHub Releases: Always marked as pre-releases to avoid confusion with electron-updater

Creator Hub App

Multi-platform builds (macOS, Windows)
Code signed and notarized
Distributed via GitHub releases and S3
PR builds available for testing
GitHub Releases: Always marked as pre-releases for later manual release when updated to "latest"

Release Strategy

The project uses a specific release strategy to ensure electron-updater works correctly:

Creator Hub releases are created as pre-release and when ready, they should be marked as "latest" on GitHub, allowing the Electron app to automatically detect and download updates
Other packages (Asset Packs, Inspector) are ALWAYS marked as pre-releases to prevent electron-updater from accidentally downloading the wrong package type
This separation ensures that users only get Creator Hub app updates through the auto-update mechanism

Asset Distribution

Asset Packs follows a controlled deployment model:

Production CDN:

Every merge to main automatically uploads assets to prod S3 CDN
Prod CDN: https://builder-items.decentraland.org/contents/:hash
Assets are immediately available after merging, matching the npm package release cycle

Development CDN:

Dev uploads are triggered manually by commenting /upload-assets on a PR
Only organization members can trigger uploads
Dev CDN: https://builder-items.decentraland.zone/contents/:hash
This prevents conflicts between multiple PRs and reduces unnecessary CI runs
Assets are content-addressed (hashed), ensuring immutability and cache correctness

🔧 Troubleshooting

Common Issues

Port Conflicts

If you encounter errors about ports already in use:

# Check what's using a port (macOS/Linux)
lsof -i :8000  # Inspector default port
lsof -i :8001  # Asset packs dev server
lsof -i :9000  # Content server

# On Windows (PowerShell)
netstat -ano | findstr :8000

Solution: Either stop the conflicting process or configure different ports via environment variables.

Permission Errors

macOS Gatekeeper Issues:

xattr -c /Applications/Decentraland\ Creator\ Hub.app/

npm Permission Errors:

# Don't use sudo! Instead, fix npm permissions:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# Add to PATH: export PATH=~/.npm-global/bin:$PATH

Build Failures

Clean and Rebuild:

make deep-clean  # Remove all node_modules and build artifacts
make init        # Fresh install and build

Protocol Buffer Issues:

make install-protoc  # Reinstall protoc
make protoc          # Regenerate proto files

Node Version Mismatch:

node --version  # Should be 22.x or higher

Use nvm to manage Node.js versions:

nvm install 22
nvm use 22

Docker Issues (Asset Packs)

Docker Not Running:

# Ensure Docker Desktop is running
docker ps  # Should list containers without error

Port 9000 Already in Use:

# Change the port in docker-compose.yml or stop the conflicting service
docker-compose down

Development Server Issues

Inspector Not Loading:

Verify WebSocket URL is correct
Check browser console for errors
Ensure CLI server is running with --data-layer flag

Asset Packs Not Showing:

Verify VITE_ASSET_PACKS_CONTENT_URL is set correctly
Check that assets were uploaded to the content server
Clear browser cache

Hot Reload Not Working:

# Restart the development server
# If using multiple terminals, restart all dev servers

TypeScript Errors

Type Errors After Update:

make typecheck  # Check all packages
npm run typecheck --workspace=packages/inspector  # Specific package

Missing Types:

npm install --save-dev @types/package-name

Getting Help

If you're still experiencing issues:

Search Existing Issues: GitHub Issues
Ask the Community: Decentraland Discord
Create a New Issue: Use our bug report template

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

For detailed contribution guidelines, see CONTRIBUTING.md.

The CI pipeline will automatically:

Lint, format & typecheck
Run all tests
Build all packages
Provide testing artifacts for review
Deploy preview versions

📚 Additional Resources

📄 License

This monorepo contains multiple packages with different licenses:

Root & Creator Hub: MIT License
@dcl/inspector: Apache License 2.0
@dcl/asset-packs: ISC License

See individual package directories for specific license details.

Made with ❤️ by the Decentraland community

Name		Name	Last commit message	Last commit date
Latest commit History 572 Commits
.ai/skills		.ai/skills
.claude		.claude
.github		.github
.vscode		.vscode
docs		docs
packages		packages
.cursorrules		.cursorrules
.editorconfig		.editorconfig
.eslintrc.json		.eslintrc.json
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
.nano-staged.js		.nano-staged.js
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.simple-git-hooks.json		.simple-git-hooks.json
.syncpackrc.json		.syncpackrc.json
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Makefile		Makefile
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Decentraland Creator Hub Monorepo

Table of Contents

🏗️ Project Structure

🚀 Quick Start

Prerequisites

Initial Setup

Testing the Bevy renderer

📋 Makefile Commands

Setup Commands

Build Commands

Development Commands

Dependency Management

Cleanup Commands

🔧 Package Scripts

Asset Packs Scripts

Inspector Scripts

Creator Hub Scripts

🔄 CI/CD Workflow

Main CI Workflow (ci.yml)

Test Workflow (tests.yml)

Asset Packs Workflow (asset-packs.yml)

Inspector Workflow (inspector.yml)

Creator Hub Workflow (creator-hub.yml)

🏗️ Architecture

Monorepo Structure

Dependency Management

Protocol Buffers

🧪 Testing

Unit Tests

End-to-End Tests

Test Structure

🚀 Development Workflow

Typical Development Flow

Local Development with Asset Packs

Launch Build Locally

Code Quality

📦 Publishing

Asset Packs Package

Inspector Package

Creator Hub App

Release Strategy

Asset Distribution

🔧 Troubleshooting

Common Issues

Port Conflicts

Permission Errors

Build Failures

Docker Issues (Asset Packs)

Development Server Issues

TypeScript Errors

Getting Help

🤝 Contributing

📚 Additional Resources

📄 License

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Main CI Workflow (`ci.yml`)

Test Workflow (`tests.yml`)

Asset Packs Workflow (`asset-packs.yml`)

Inspector Workflow (`inspector.yml`)

Creator Hub Workflow (`creator-hub.yml`)