billi-framework

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/

• bin/billi.js - CLI entry point
• lib/server.js - Core server
• lib/router.js (optional) - Routing logic
• lib/renderer.js (optional) - SSR renderer
• 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

• Create repository: billi-framework
• Use monorepo structure with /packages
• Add GitHub Actions for CI/CD
• 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:

• Test installation: npx create-billi-app@latest my-app
• Create documentation site
• Add examples to GitHub
• Create video tutorials
• Write blog posts
• Submit to awesome lists
• 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