Developer Reference

Project Documentation

Setup, workflow, component patterns, and deployment reference for the SignatureWEB EE boilerplate.

How It Works

Every page, component, and template is written in ./project-static-html/ first. The same files drive both the static HTML preview and the ExpressionEngine deployment.

project-static-html/src/templates/
├── index.njk              (home page)
└── pages/*.njk            (all other pages)
    │
    ▼  npm run dev / npm run build:html
project-static-html/dist/  (static HTML preview)
    │
    ▼  npm run build-seeds
project-static-html/src/seeds/*.seed.json
    │
    ▼  npm run seed  (on the server)
ExpressionEngine entries + Bloqs blocks + Structure pages
    


    
Each component .njk file also contains an embedded @ee-template block — the exact EE template syntax that migrations write to exp_templates. Running npm run update re-syncs those blocks to the EE database without a full reset.

Local Setup

cd project-static-html
npm install
npm run dev
# Open http://localhost:5173

NPM Commands

Run from project-static-html/ :

Command What it does
npm run dev Build HTML + CSS, watch all sources, start Vite dev server at localhost:5173
npm run build Full production build: clean → HTML → CSS → JS (minified, hashed)
npm run build:html Nunjucks → HTML + copy static assets to dist/
npm run build:css Sass → PostCSS (Tailwind + autoprefixer) → dist/assets/css/main.css
npm run preview Production build + serve at localhost:4173
npm run format Prettier format all JS, JSON, CSS, NJK files
npm run build-seeds Generate all *.seed.json / *.seed.yaml from page templates
npm run build-seeds -- --page=url_title Regenerate seed for a single page by url_title

Run from project root — local machine (provisioning):

Command What it does
npm run provision:server LEMP stack only — nginx, PHP 8.3-FPM, MySQL, sudo user, UFW firewall, swap, fail2ban
npm run provision:ee EE deploy only — clone repo, import base DB, create .env.php, configure SSL and Node.js
npm run provision Full provision — LEMP + bare EE install (no migrations or content)
npm run full-deploy One-shot: LEMP + EE + reset + migrate + seed — fresh server to fully deployed site

Run from project root — on the server:

Command What it does
npm run migrate Run all pending EE migrations
npm run reset Roll back ALL migrations (auto-snapshots DB first)
npm run deploy Shortcut: reset → migrate → seed
npm run update git pull → re-sync EE templates → update Bloqs atom settings + cache clear
npm run seed Seed all pages to EE (skips entries that already exist)
npm run seed -- url_title Seed a single page by url_title
npm run update-seed -- <entry_id> Re-seed an existing entry — replaces Bloqs blocks, preserves entry and Structure placement
npm run snapshot Dump gzipped DB backup to backups/ (keeps last 10)

Deployment Workflow

Provision a fresh server

Run from your local machine. Prompts for server IP, domain, MySQL credentials, and GitHub PAT.

# One-shot: LEMP + EE + full content deploy
npm run full-deploy

# Step by step (use when the server already hosts legacy sites):
npm run provision:server   # LEMP stack only
npm run provision:ee       # EE deploy — reads saved server config, skips re-prompting

First deploy on an already-provisioned server

npm run migrate   # Create channels, fields, Bloqs blocks, EE templates
npm run seed      # Create EE entries and Structure pages
                        

                            Then in EE CP:
                            Developer → Pro Variables → New Variable
                            — name:
                            root_url
                            , value:
                            https://your-domain.com/
                            (trailing slash required).

Template changes only (non-destructive)

git push
npm run update   # git pull + re-sync all EE templates + cache clear

Adding new Bloqs components or fields

npm run reset    # Roll back all migrations (⚠ destructive — auto-snapshots DB first)
npm run migrate  # Re-run from scratch
npm run seed     # Re-populate all entries

Full reset (shortcut)

npm run deploy   # reset → migrate → seed

Further Reading

Detailed documentation lives in the documentation/ directory of the repo.

File Purpose
documentation/DEVELOPER-README.md Full frontend developer guide — component patterns, design tokens, icon system, seed rules
documentation/STATIC-HTML-README.md Static HTML build system internals — build.js, snippet extraction, watch mode
documentation/EE_DEPLOYMENT_README.md EE deployment pipeline — migrations, deploy_tools addon, template sync
documentation/SEEDING-CONTENT.md Content seeding system — build-seeds.js, seed file format, SeedRunner
documentation/PROVISIONING.md Post-migration EE CP checklist — Pro Variables, file permissions, upload directories
documentation/SERVER_SETUP_RUNBOOK.md Full server provisioning runbook — nginx, PHP, MySQL, SSL, wildcard subdomains
CLAUDE.md AI assistant context — server details, EE rules, known issues, quick reference commands