Builder

A zero-touch project generator & GitHub Pages deployer built with NestJS.

Builder is an npm package (Nest project) you invoke during a build. It scaffolds a project from parameters, installs dependencies, builds it, and deploys the generated HTML/CSS/JS to GitHub Pages — end-to-end, in one command.

Table of Contents

• Features
• How It Works
• Prerequisites
• Installation
• Quick Start
• Parameters

Features

• One-shot pipeline: generate → install → build → deploy to GitHub Pages.
• Parameter-driven scaffolding (no interactive prompts).
• Works locally & in CI (non-interactive).
• Supports npm / yarn / pnpm with auto-detection.
• Dry-run and verbose logging modes.
• Custom domain support (writes CNAME).

How It Works

┌──────────┐   ┌────────────────────┐   ┌───────────────┐   ┌──────────────┐
│  Params   ──▶ Project Generator   ──▶  Dependencies   ──▶    Builder    └──────────┘   └────────────────────┘   └───────────────┘   └──────┬───────┘
                                                                   |
                                                                   ▼
                                                            ┌──────────────┐
                                                            │   Deployer   │
                                                            │(GitHub Pages)|
                                                            └──────────────┘

Under the hood, Builder is a NestJS app with modules like GeneratorModule, PackageManagerModule, BuildModule, and DeployModule.

Prerequisites

• Node.js 18+
• git installed and available in PATH
• A GitHub repository to deploy to
• A GitHub token with repo (and pages if needed) scopes
  In GitHub Actions, the built-in ${{ secrets.GITHUB_TOKEN }} works with proper permissions.

Installation

Use directly with npx (recommended in CI) or install as a dev dependency.

# one-off
npx builder@latest --help

# or install
npm i -D builder
# yarn add -D builder
# pnpm add -D builder

Quick Start

Deploy a preconfigured template to gh-pages:

npx builder \
  --name "my-app" \
  --template minimal \
  --repo "owner/my-repo" \
  --branch main \
  --token $GITHUB_TOKEN

| Tip: In a monorepo, run Builder from the package directory or point --config to the correct path.

node dist/main.js <projectType> <repoPath> <repoUrl> <branch> <githubToken>

Parameters

• projectType — Template/stack to generate (e.g. nextra). Used by ProjectFactoryService.create(projectType, branch).

• repoPath — Where to prepare the working copy:

• "workspace" — use process.env.GITHUB_WORKSPACE (or .) and the content/ subfolder: tempRepoRoot = $GITHUB_WORKSPACE/content

• a path (absolute or relative to the package root) — clone/sync the repo into that folder (e.g. ./content).

• repoUrl — Git URL of the repo to work with (e.g. https://github.com/owner/repo.git).

• branch — Branch to checkout/pull and deploy from, e.g. main.

• githubToken — Token used by git operations (clone/fetch/push). Provide a PAT locally, or ${{ secrets.GITHUB_TOKEN }} in Actions.

# 1) Get the builder source
git clone <builder-repo-url>
cd builder
git init            # if not already a git repo
npm install
npm run build       # produces dist/main.js

# 2) Prepare your target repo (first time)
git clone https://github.com/owner/repo.git
# (or let Builder clone/sync into ./content)

# 3) Run Builder against your target repo
node dist/main.js nextra ./content https://github.com/owner/repo.git main $GITHUB_TOKEN

# After you’ve made changes to Builder itself:
npm version patch   # or minor / major
npm run build       # ensure dist/main.js is up-to-date
npm publish         # requires npm auth

# Use it elsewhere:
npx builder nextra ./content https://github.com/owner/repo.git main $GITHUB_TOKEN
# or install as a dev dependency and expose a bin:
# package.json: "bin": { "builder": "dist/main.js" }