NPM Package Distribution

Prism packages can be published to the npm public registry under the @prism-dx scope, making them available to anyone via CDN without needing npm installed.

Why npm?

✅ Universal Access — Anyone can install, no custom registries ✅ CDN Distribution — unpkg.com provides fast global delivery ✅ Versioning — Built-in semver support ✅ Discovery — Searchable on npmjs.com ✅ No Dependencies — Fetch packages without installing npm!

Available Packages

All packages are published under the @prism-dx scope:

For Users: Installing Prisms

The Prism installer automatically fetches prisms from npm:

python3 install.py
# Select a prism from the list — automatically fetched from npm!

# Or specify directly:
python3 install.py --prism fortune500

Method 2: Manual fetch

# List available prisms
python3 scripts/npm_package_fetcher.py list

# Fetch a specific prism
python3 scripts/npm_package_fetcher.py fetch @prism-dx/prism

# Fetch specific version
python3 scripts/npm_package_fetcher.py fetch @prism-dx/startup --version 1.0.0

Method 3: Direct npm install (if you have npm)

npm install @prism-dx/prism

Method 4: Direct CDN access (no tools needed)

# Download package.yaml
curl https://unpkg.com/@prism-dx/prism@latest/package.yaml

For Maintainers: Publishing Prisms

Prerequisites

  1. npm account — Create at npmjs.com
  2. @prism-dx scope access — Request access via GitHub issues
  3. npm CLI installed: 
    # Mac
brew install node

# Linux
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows
winget install OpenJS.NodeJS

Login to npm

npm login

Publish a prism

Test first (dry run)

python3 scripts/publish_packages.py --package prism --dry-run
python3 scripts/publish_packages.py --all --dry-run

Publish

python3 scripts/publish_packages.py --package prism
python3 scripts/publish_packages.py --all

Manual publishing

cd prisms/prism.prism
npm publish --access public

Updating Prisms

1. Update version

Edit prisms/PRISM_NAME/package.yaml:

package:
  version: "1.1.0"   # increment version

2. Update changelog

Add notes in the prism’s README.md.

3. Publish

python3 scripts/publish_packages.py --package PRISM_NAME

Package Structure for npm

Each prism directory published to npm:

prisms/prism.prism/
├── package.json      # npm metadata (required for publishing)
├── package.yaml      # Prism manifest
├── README.md         # Prism documentation
├── base/             # Base sub-prism configs
├── profiles/         # Profile sub-prism configs (optional)
└── welcome.yaml      # Welcome content (optional)

package.json example

{
  "name": "@prism-dx/prism",
  "version": "1.0.0",
  "description": "Prism for freelancers and indie developers",
  "main": "package.yaml",
  "files": [
    "package.yaml",
    "base/",
    "profiles/",
    "welcome.yaml",
    "resources.yaml",
    "README.md"
  ],
  "keywords": ["prism", "dev-environment", "personal", "freelancer"],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/andersonwilliam85/prism.git",
    "directory": "prisms/prism.prism"
  }
}

How It Works

For users

  1. Prism installer starts — user selects a prism
  2. Fetcher queries unpkg CDN for the prism’s package.yaml
  3. Downloads and caches the prism locally
  4. Falls back to local prisms/ directory if npm is unavailable
  5. Engine merges selected sub-prisms and installs the environment

For maintainers

  1. Create or update the prism in prisms/PRISM_NAME/
  2. Increment package.yaml version and package.json version
  3. Test locally
  4. Run publish script → automatically available via CDN

unpkg CDN URLs

https://unpkg.com/@prism-dx/PRISM-NAME@VERSION/FILE

Examples:

# Latest version
https://unpkg.com/@prism-dx/prism@latest/package.yaml

# Specific version
https://unpkg.com/@prism-dx/startup@1.0.0/package.yaml

# Browse entire prism
https://unpkg.com/browse/@prism-dx/fortune500@latest/

Versioning Strategy

Follow Semantic Versioning:

Fallback Mechanism

1. Try unpkg CDN (fast, global)
   ↓ if fails
2. Try npm registry directly
   ↓ if fails
3. Use local prisms/ directory
   ↓ if fails
4. Show error with manual download instructions

Prism works even without internet access if you have the repo cloned locally.

Troubleshooting

“403 Forbidden” when publishing

npm whoami    # check you're logged in
npm login     # login if needed

“Package already exists” — increment the version in package.json and package.yaml.

“unpkg CDN unavailable” — the installer automatically falls back to local prisms.

Resources