@manifold-studio/create-app

CLI tool for scaffolding new Manifold Studio projects. Get started with 3D modeling in TypeScript with hot reloading, parametric controls, and export functionality in seconds.

🚀 Quick Start

Create a new 3D modeling project instantly:

# Create a new project
npm create @manifold-studio/app my-3d-project

# Set up for local development (until packages are published)
cd my-3d-project
npm install
npm link @manifold-studio/wrapper @manifold-studio/configurator

# Start developing
npm run dev

This single command automatically:

• Discovers your models (main.ts + components/)
• Starts development server (single server with integrated pipeline compiler)
• Watches for changes and regenerates pipeline entries
• Opens browser with live 3D preview and parameter controls

What you get:

• 3D Canvas: Real-time model preview with camera controls
• Parameter Panel: Sliders and controls for your model parameters
• Export Tools: Download STL, OBJ, GLB files instantly
• Hot Reloading: Edit code and see changes immediately
• Automatic Model Discovery: Add new .ts files and they appear instantly

🔧 CLI-Powered Development

Generated projects use the Manifold Studio CLI for development, which provides:

Unified Development Experience

The npm run dev command in generated projects runs the Manifold Studio CLI, which:

1. Automatically discovers models in your project (main.ts + components/)
2. Generates pipeline entries dynamically without manual management
3. Starts single development server (port 3000):
   • Template Server: Configurator interface with HMR
   • Integrated Pipeline Compiler: Model compilation and manifest generation
4. Watches for file changes and regenerates pipeline automatically
5. Provides source-based configurator imports for immediate feedback

Configurator Development Integration

For configurator library development, use the CLI in test projects:

# Navigate to test project (not create-app package)
cd reference-project
npm run dev  # CLI automatically detects configurator development mode

Benefits of CLI approach:

• No manual pipeline management: CLI handles everything automatically
• Automatic model discovery: New .ts files appear in UI instantly
• Unified configuration: Consistent Vite aliases across both servers
• Better import resolution: Package imports work in generated pipeline files
• Reduced generated code: Shared types/functions moved to library

✨ What You Get

Every scaffolded project includes:

• TypeScript by default with full type safety and IDE support
• Parametric box example with width, height, depth controls to get you started
• Component system for modular model development and organization
• Hot module reloading for instant feedback during development
• Export functionality built-in for STL, OBJ, and GLB formats
• Modern tooling with Vite, TypeScript, and ESM support
• Model discovery that automatically finds and lists your 3D models

Generated Project Structure

my-3d-project/
├── main.ts              # Your main 3D model with parametric controls
├── components/          # Additional model components
│   └── example.ts       # Example component showing best practices
├── package.json         # Dependencies and scripts (includes CLI integration)
├── tsconfig.json        # TypeScript configuration
├── index.html           # HTML bootstrap for the browser interface
└── README.md            # Project-specific documentation

📦 CLI Options

Basic Usage

npm create @manifold-studio/app <project-name>

Available Options

npm create @manifold-studio/app my-project [options]

Options:
  -t, --template <template>  Template to use (default: "basic")
  --no-install              Skip automatic dependency installation
  -h, --help                Display help information
  -V, --version             Display version number

Usage Examples

# Create project with default settings
npx @manifold-studio/create-app my-models

# Create project without installing dependencies
npx @manifold-studio/create-app my-models --no-install

# Specify template explicitly (currently only "basic" available)
npx @manifold-studio/create-app my-models --template basic

🏗️ Generated Project Structure

Core Files

• main.ts: Your primary 3D model file with parametric configuration
• components/: Directory for additional model components and utilities
• components/example.ts: Example component demonstrating best practices

Configuration Files

• package.json: Configured with Manifold Studio dependencies and CLI integration
• tsconfig.json: TypeScript configuration optimized for 3D modeling
• index.html: Bootstrap HTML that loads the Manifold Studio configurator

Component Discovery System

The generated project automatically discovers models using a convention-based approach:

1. Main Model: main.ts is always available as the primary model
2. Component Models: Any .ts files in components/ that export a default function or parametric config
3. Automatic Registration: Models appear in the UI dropdown without manual registration
4. Hot Reloading: Changes to any model file trigger immediate browser updates

🔧 How the Package Works

Template System

The create-app tool uses Handlebars for template processing:

• Template Location: templates/basic/ contains the base project template
• Variable Substitution: Project name and other variables are injected into template files
• File Processing: .hbs files are processed and renamed (e.g., package.json.hbs → package.json)
• Static Files: Non-template files are copied directly to the target directory

Dependency Management

Generated projects are configured with:

{
  "dependencies": {
    "@manifold-studio/wrapper": "^1.0.0",
    "@manifold-studio/configurator": "^1.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.2",
    "vite": "^5.0.0"
  }
}

Local Development Workflow

For development with unpublished packages, the tool supports npm link:

1. Build packages: npm run build in the monorepo root
2. Create links: npm link in each package directory
3. Link in project: npm link @manifold-studio/wrapper @manifold-studio/configurator
4. Development: Changes in wrapper/configurator packages propagate to your project

🛠️ Development Workflow

Working with Generated Projects

1. Start CLI Development Server:

   npm run dev  # Runs Manifold Studio CLI automatically

2. Edit Models: Modify main.ts or add files to components/

   • Automatic Discovery: New .ts files appear in UI dropdown instantly
   • Pipeline Regeneration: CLI detects changes and updates pipeline automatically

3. See Changes Instantly:

   • Model Changes: Pipeline rebuilds and GLB updates automatically
   • Configurator Changes: HMR provides immediate feedback (if developing configurator)

4. Export Models: Use the built-in export tools to download STL, OBJ, or GLB files

Component Development Patterns

Simple Component:

// components/wheel.ts
import { Manifold } from "@manifold-studio/wrapper";

export default function createWheel(radius = 10, width = 5) {
  return Manifold.cylinder(width, radius);
}

Parametric Component:

// components/bracket.ts
import { Manifold, P, createConfig } from "@manifold-studio/wrapper";

export default createConfig(
  {
    width: P.number(20, 10, 50, 1),
    height: P.number(15, 10, 40, 1),
    thickness: P.number(3, 1, 10, 0.5),
  },
  (params) => {
    // Your bracket logic here
    return Manifold.cube([params.width, params.height, params.thickness]);
  },
  {
    name: "Parametric Bracket",
    description: "Adjustable mounting bracket",
  }
);

Model Discovery Conventions

• Entry Point: main.ts serves as the primary model
• Components: Files in components/ are automatically discovered
• Export Requirements: Models must export either:
  • A default function that returns a Manifold
  • A default parametric config created with createConfig()
• File Extensions: Only .ts files are processed
• Naming: File names become model names in the UI dropdown

📋 Requirements

System Requirements

• Node.js: Version 16.0.0 or higher
• NPM: Version 7.0.0 or higher (for workspace support)
• Operating System: Windows, macOS, or Linux

Browser Compatibility

Generated projects work in modern browsers that support:

• ES Modules: Chrome 61+, Firefox 60+, Safari 10.1+
• WebAssembly: Chrome 57+, Firefox 52+, Safari 11+
• Top-level await: Chrome 89+, Firefox 89+, Safari 15+

Development Environment

• TypeScript: Full IDE support with IntelliSense
• Vite: Fast development server with HMR
• Modern JavaScript: ES2022+ features supported

🔗 Integration with Manifold Studio

Package Ecosystem

The create-app tool generates projects that depend on:

• @manifold-studio/wrapper: Core ManifoldCAD API with operation tracking
• @manifold-studio/configurator: UI components and development environment

Cross-Package Development

When developing Manifold Studio itself:

1. Wrapper Changes: TypeScript watch rebuilds automatically (~1-2 seconds)
2. Configurator Updates: Vite HMR propagates changes to generated projects
3. Total Latency: ~2-3 seconds for cross-package changes to appear in browser

Development Commands in Generated Projects

# Start CLI development server (recommended)
npm run dev  # Runs Manifold Studio CLI with automatic model discovery

# Legacy commands (if available in project)
npm run build:pipeline  # Manual pipeline compilation
npm run dev:ui          # UI server only
npm run dev:pipeline    # Pipeline compiler only

# Utility commands
npm run type-check      # TypeScript type checking

🚨 Troubleshooting

Common Issues

"Module not found" errors

Error: Cannot resolve module '@manifold-studio/wrapper'

Solution: For local development, ensure packages are linked:

# In the manifold-studio monorepo root
npm run build
cd packages/wrapper && npm link
cd ../configurator && npm link

# In your generated project
npm link @manifold-studio/wrapper @manifold-studio/configurator

TypeScript compilation errors

Error: Cannot find type definitions

Solution: Ensure TypeScript configuration is correct:

// tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}

Development server won't start

Error: Port 3000 is already in use

Solution: The CLI uses port 3000 for the development server. Stop other servers or check for conflicts:

# Check what's using the port
lsof -i :3000

# Kill processes if needed
kill -9 <PID>

NPM Link Workflow Issues

Links not working after package updates

Solution: Re-create the links:

# Remove old links
npm unlink @manifold-studio/wrapper @manifold-studio/configurator

# Rebuild and re-link
cd /path/to/manifold-studio
npm run build
cd packages/wrapper && npm link
cd ../configurator && npm link

# Re-link in your project
npm link @manifold-studio/wrapper @manifold-studio/configurator

Dependency version conflicts

Solution: Ensure consistent versions across packages:

# Check linked package versions
npm ls @manifold-studio/wrapper
npm ls @manifold-studio/configurator

# If versions don't match, rebuild the monorepo
cd /path/to/manifold-studio
npm run build

Browser Issues

WASM loading failures

Error: WebAssembly module failed to load

Solution: Ensure you're serving the project over HTTP (not file://):

# Use the development server
npm run dev

# Don't open index.html directly in browser

Hot reloading not working

Solution: Check that the development server is running and accessible:

1. Verify npm run dev is running without errors
2. Check browser console for connection errors
3. Ensure firewall isn't blocking the development server

📄 License & Links

License

MIT License - see the LICENSE file for details.

Related Packages

• @manifold-studio/wrapper - Core ManifoldCAD API wrapper with operation tracking
• @manifold-studio/configurator - Browser-based development environment
• ManifoldCAD - The underlying 3D modeling library

Repository

• GitHub: manifold-cad-live-preview
• Package Directory: packages/create-app
• Issues: GitHub Issues

Built with ❤️ for the 3D modeling community