tomevault-io Astro Build Skill
Build and verify the jmrp.io Astro 6 SSG project.
Build Commands
Full Production Build (Atomic Swap)
pnpm build
This runs: astro build → atomic swap (dist_new → dist_old → dist) → Prettier check.
Deployment: The project lives at
/var/www/jmrp.io/on the production server. Nginx serves/var/www/jmrp.io/dist/directly as the document root forjmrp.io. Runningpnpm buildon the server immediately updates the live website — no git push or separate deploy step is needed. The atomic swap ensures zero-downtime deploys.
Development Server
pnpm dev
Starts on port 4321. Warning: Dev server lacks nonces/SRI — do not run tests against it.
Preview Production Build
pnpm preview
Serves dist/ on port 4321. Use this for testing.
Full QA Pipeline (pnpm verify)
pkill -f "astro dev" 2>/dev/null # Stop dev server first!
pnpm verify
Runs scripts/run-verify.mjs — 14 sequential steps (fail-fast except SonarCloud):
| # | Step | Command |
|---|---|---|
| 1 | Static: Astro Check | pnpm typecheck --minimumFailingSeverity warning |
| 2 | Static: ESLint | pnpm lint --max-warnings=0 |
| 3 | Static: Prettier | pnpm exec prettier --check . |
| 4 | Lint: CSS Stylelint | pnpm lint:css |
| 5 | Build: Production Build | pnpm run build |
| 6 | Lint: HTML5 Validation | pnpm lint:html |
| 7 | Lint: RSS Feed | node scripts/ci/validate-rss.mjs dist |
| 8 | Lint: Schema.org JSON-LD | node scripts/ci/validate-schema.mjs dist |
| 9 | Lint: Spelling (CSpell) | pnpm exec cspell lint . |
| 10 | Lint: Broken Links (Lychee) | lychee --config lychee.toml --root-dir dist dist/**/*.html |
| 11 | Lint: JSDoc Coverage | node scripts/ci/calculate-jsdoc-coverage.mjs |
| 12 | Security: SonarCloud Analysis | pnpm exec sonar-scanner (if SONAR_TOKEN set) |
| 13 | Analyze: SonarCloud Issues | node scripts/ci/get-sonar-issues.mjs (if SONAR_TOKEN + SONAR_PROJECT_KEY) |
| 14 | Tests: Playwright E2E | pnpm test:e2e |
Individual Checks
pnpm typecheck # astro check
pnpm lint # ESLint
pnpm lint:css # Stylelint
pnpm test:e2e # Playwright tests
pnpm verify-icons # Icon consistency (not in verify pipeline)
pnpm exec cspell lint . # Spell check (bilingual EN/ES)
pnpm exec prettier --check . # Format check
pnpm lint:html # HTML5 validation (requires build)
SonarCloud Analysis
Check Issues & Hotspots Manually
# Requires SONAR_TOKEN and SONAR_PROJECT_KEY env vars
SONAR_PROJECT_KEY=jmrplens_jmrp.io node scripts/ci/get-sonar-issues.mjs
This script queries the SonarCloud API for:
- Open issues — bugs, code smells, vulnerabilities
- Security hotspots — items marked TO_REVIEW
- Checks local files for
NOSONARsuppression comments
Run SonarCloud Scanner
pnpm exec sonar-scanner # Requires SONAR_TOKEN
SonarCloud Dashboard
- URL:
https://sonarcloud.io/dashboard?id=jmrplens_jmrp.io - Project key:
jmrplens_jmrp.io - Organization:
jmrplens - Config:
sonar-project.properties
SonarLint IDE Integration
VS Code has SonarLint connected mode configured in .vscode/settings.json:
- Connection ID:
jmrplens - Project key:
jmrplens_jmrp.io - Provides real-time issue detection in the editor
Issue Suppressions
sonar-project.properties defines multicriteria suppressions for CI scripts that intentionally use execSync/execFileSync and regex patterns. These suppress S4721 (OS Command Injection), S5852 (Regex complexity), and S4036 (OS command shell PATH) in specific files.
Common Issues
- Build fails with nonce errors: The
NGINX_CSP_NONCEplaceholder is expected — it's replaced by Nginx at runtime. - Tests fail with CSP errors: Stop
astro devfirst (pkill -f "astro dev"). - Port 4321 in use: Kill existing processes:
lsof -ti:4321 | xargs kill.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.