Skip to content

EXTERNAL-DEVELOPER-SETUP.md

Latest commit

 

History

History
191 lines (131 loc) · 4.13 KB

EXTERNAL-DEVELOPER-SETUP.md

File metadata and controls

191 lines (131 loc) · 4.13 KB

Quick Start Guide for External Developers

This guide is for developers who want to try out Blit-Tech Demos before Blit-Tech is published to npm.

Why This Setup Is Needed

Blit-Tech Demos depends on Blit-Tech via a pnpm workspace dependency:

{
  "dependencies": {
    "blit-tech": "workspace:*"
  }
}

Since Blit-Tech is not yet on npm, you need to clone both repositories and set up a local workspace.

Browser Requirements

The demos require WebGPU support:

  • Chrome/Edge 113+
  • Firefox 141+ on Windows; 145+/147+ on macOS; Nightly on Linux
  • Safari 26+; or Safari 18-25 with WebGPU enabled via Feature Flags

One-Time Setup

1. Create Workspace Directory

mkdir blit-tech-workspace
cd blit-tech-workspace

2. Clone Both Repositories

git clone https://github.com/vancura/blit-tech.git
git clone https://github.com/vancura/blit-tech-demos.git

3. Create Workspace Configuration

Create a pnpm-workspace.yaml file in the workspace root:

cat > pnpm-workspace.yaml << 'EOF'
packages:
  - "blit-tech"
  - "blit-tech-demos"
EOF

4. Install Dependencies

pnpm install

Directory Structure

After setup, your directory should look like this:

blit-tech-workspace/          # Your workspace root
├── pnpm-workspace.yaml       # Links the two packages
├── package.json              # Optional (see below)
├── node_modules/             # Shared dependencies
├── blit-tech/                # The library
│   ├── src/
│   ├── dist/                 # Built output
│   └── package.json
└── blit-tech-demos/          # The demos
    ├── src/                  # One JS file per demo (single source of truth)
    ├── _partials/            # Shared HTML template
    ├── plugins/              # virtual-demos Vite plugin
    └── package.json

Optional: Add package.json

You can optionally create a package.json in the workspace root:

Prerequisite: Node.js >= 20.0.0 is required before installing pnpm.

{
  "name": "blit-tech-workspace",
  "version": "0.0.0",
  "private": true,
  "packageManager": "pnpm@10.26.2"
}

This is not required but can help with pnpm version pinning.

Running the Demos

Standard Development

cd blit-tech-demos
pnpm dev

Opens browser at http://localhost:5173/demos/001-basics.html (or visit /demos/ for the full index).

Development with Auto-Rebuild

If you want to edit the Blit-Tech library and see changes instantly:

cd blit-tech-demos
pnpm dev:watch

This runs two processes concurrently:

  • Watches blit-tech/src and rebuilds on changes
  • Runs Vite dev server with hot module reload

Building from Scratch

If you want to rebuild the library:

cd blit-tech
pnpm build

Then the demos will use the newly built version.

After npm Publication

Once Blit-Tech is published to npm, you can:

  1. Clone just blit-tech-demos
  2. Run pnpm install
  3. Start developing

The workspace setup will no longer be needed.

Troubleshooting

Error: "Cannot find package 'blit-tech'"

Cause: Workspace structure not set up correctly

Fix: Ensure you have:

  • Both repos cloned as siblings
  • pnpm-workspace.yaml in the parent directory
  • Ran pnpm install from the workspace root

Error: "No matching version found for blit-tech@workspace:*"

Cause: pnpm can't find the workspace

Fix: Check that:

  • pnpm-workspace.yaml exists in the parent directory
  • Both Blit-Tech and Blit-Tech Demos are listed in the config
  • You're running commands from inside the workspace structure

Demos won't start - "TypeError: Cannot read properties..."

Cause: Blit-Tech library not built

Fix:

cd blit-tech
pnpm install
pnpm build
cd ../blit-tech-demos
pnpm dev

Alternative: Wait for npm Publication

If this setup seems complex, you can wait for Blit-Tech to be published to npm. Once published, installation will be a simple:

npm create vite@latest my-demo --template vanilla
cd my-demo
npm install blit-tech

Check the Blit-Tech repository for publication status.