Billi Framework - Package Setup Guide

This guide explains how to set up the Billi framework for publishing to npm.

Project Structure

You'll need two separate npm packages:

billi-framework/
├── packages/
│   ├── create-billi-app/        # CLI installer package
│   │   ├── index.js
│   │   ├── package.json
│   │   └── README.md
│   └── billi/                   # Core framework package
│       ├── bin/
│       │   └── billi.js
│       ├── lib/
│       │   └── server.js
│       ├── package.json
│       └── README.md
└── README.md

Package 1: create-billi-app

package.json

{
  "name": "create-billi-app",
  "version": "1.0.0",
  "description": "Create Billi apps with one command",
  "main": "index.js",
  "bin": {
    "create-billi-app": "./index.js"
  },
  "keywords": [
    "billi",
    "react",
    "framework",
    "ssr",
    "scaffolding",
    "cli"
  ],
  "author": "Your Name",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/create-billi-app"
  },
  "engines": {
    "node": ">=16.0.0"
  },
  "dependencies": {},
  "files": [
    "index.js",
    "README.md"
  ]
}

Publishing Steps

cd packages/create-billi-app
npm login
npm publish

Users will then run:

npx create-billi-app@latest my-app

Package 2: billi (Core Framework)

package.json

{
  "name": "billi",
  "version": "1.0.0",
  "description": "A modern React framework with SSR, routing, and more",
  "main": "lib/server.js",
  "bin": {
    "billi": "./bin/billi.js"
  },
  "keywords": [
    "billi",
    "react",
    "framework",
    "ssr",
    "server-side-rendering",
    "routing",
    "api-routes"
  ],
  "author": "Your Name",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/billi"
  },
  "engines": {
    "node": ">=16.0.0"
  },
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "dependencies": {
    "chokidar": "^3.5.3"
  },
  "devDependencies": {
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  },
  "files": [
    "bin/",
    "lib/",
    "README.md"
  ]
}

File Structure

bin/billi.js:

• Make sure first line is: #!/usr/bin/env node
• Make file executable: chmod +x bin/billi.js

lib/server.js:

• Core server implementation
• Export BilliServer class

Publishing Steps

cd packages/billi
chmod +x bin/billi.js
npm login
npm publish

Local Development & Testing

Before publishing, test locally:

1. Link packages locally

# Link the core framework
cd packages/billi
npm link

# Link the CLI
cd ../create-billi-app
npm link

# Test in a new project
mkdir test-app
cd test-app
npx ../packages/create-billi-app test-project
cd test-project
npm link billi
npm run dev

2. Test with npm pack

cd packages/billi
npm pack
# This creates billi-1.0.0.tgz

cd packages/create-billi-app
npm pack
# This creates create-billi-app-1.0.0.tgz

# Install in test project
npm install /path/to/billi-1.0.0.tgz

Version Management

Use semantic versioning:

• Major (1.0.0): Breaking changes
• Minor (1.1.0): New features, backwards compatible
• Patch (1.0.1): Bug fixes

Update versions in both packages:

# Update version
npm version patch  # or minor, or major

# Publish
npm publish

Environment Setup

Required Files in packages/billi/

1. bin/billi.js - CLI entry point
2. lib/server.js - Core server
3. lib/router.js (optional) - Routing logic
4. lib/renderer.js (optional) - SSR renderer
5. lib/middleware.js (optional) - Middleware handler

Dependencies to Install

cd packages/billi
npm install chokidar      # File watching
npm install --save-dev react react-dom

Publishing Checklist

Before publishing:

• [ ] Test locally with npm link
• [ ] Update version numbers
• [ ] Update README files
• [ ] Add LICENSE file
• [ ] Test installation: npx create-billi-app@latest test
• [ ] Verify all files included (check files in package.json)
• [ ] Make bin files executable
• [ ] Add .npmignore if needed
• [ ] Test on clean install
• [ ] Check npm registry name availability

.npmignore

Create .npmignore in each package:

# Development files
node_modules/
.git/
.gitignore
*.log

# Test files
test/
tests/
__tests__/
*.test.js

# Documentation
docs/
examples/

# Build files
.DS_Store
*.swp
*.swo

GitHub Repository Setup

1. Create repository: billi-framework
2. Use monorepo structure with /packages
3. Add GitHub Actions for CI/CD
4. Create releases for each version

Example GitHub Action (.github/workflows/publish.yml)

name: Publish to NPM

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      
      - name: Install dependencies
        run: |
          cd packages/billi && npm install
          cd ../create-billi-app && npm install
      
      - name: Publish billi
        run: cd packages/billi && npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      
      - name: Publish create-billi-app
        run: cd packages/create-billi-app && npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Quick Start Commands

# 1. Initialize project
mkdir billi-framework && cd billi-framework
npm init -y

# 2. Create package structure
mkdir -p packages/billi/{bin,lib}
mkdir -p packages/create-billi-app

# 3. Copy files
# - Copy server.js to packages/billi/lib/
# - Copy billi.js to packages/billi/bin/
# - Copy index.js (CLI) to packages/create-billi-app/

# 4. Make executable
chmod +x packages/billi/bin/billi.js
chmod +x packages/create-billi-app/index.js

# 5. Test locally
cd packages/billi && npm link
cd ../create-billi-app && npm link

# 6. Create test app
npx create-billi-app test-app
cd test-app
npm link billi
npm run dev

# 7. Publish (when ready)
cd packages/billi && npm publish
cd ../create-billi-app && npm publish

Post-Publication

After publishing:

1. Test installation: npx create-billi-app@latest my-app
2. Create documentation site
3. Add examples to GitHub
4. Create video tutorials
5. Write blog posts
6. Submit to awesome lists
7. Share on social media

Troubleshooting

"Command not found: billi"

• Check bin field in package.json
• Verify file is executable: chmod +x bin/billi.js
• Check shebang: #!/usr/bin/env node

"Cannot find module"

• Check main field in package.json
• Verify files exist in published package
• Use npm pack to inspect package contents

"Permission denied"

• Make sure bin files are executable
• On Windows, this shouldn't be an issue

Resources

• npm Documentation
• Semantic Versioning
• Publishing Packages
• CLI Best Practices

Support

For issues or questions:

• GitHub Issues: github.com/yourusername/billi/issues
• Discord: discord.gg/billi
• Twitter: @billiframework