Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
92 lines (66 loc) · 2.71 KB

DEVELOPMENT.md

File metadata and controls

92 lines (66 loc) · 2.71 KB
Raw

Development Guide

This project is a static Next.js app. It should stay compatible with GitHub Pages hosting and browser-local file processing unless the deployment and privacy model intentionally changes.

Requirements

  • Node.js 20 or newer
  • npm
  • Git

On Windows PowerShell, use npm.cmd run ... if execution policy blocks the npm shim.

Local Setup

git clone https://github.com/zxyandreay/followback-checker.git
cd followback-checker
npm install
npm run dev

Open:

http://localhost:3000/followback-checker

The /followback-checker path is required because next.config.ts sets both basePath and assetPrefix for GitHub Pages.

Scripts

Command Purpose
npm run dev Start the Next.js development server
npm run lint Run ESLint checks
npm run test Run Vitest unit tests from src/**/*.test.ts
npm run build Build the static export into out/
npm run start Start Next.js in production mode after a build; not used by the GitHub Pages workflow

There is no separate typecheck script in package.json.

Static Export and Deployment

Static export settings live in next.config.ts:

const nextConfig = {
  output: "export",
  basePath: "/followback-checker",
  assetPrefix: "/followback-checker",
  images: {
    unoptimized: true,
  },
};

npm run build writes the static site to out/. The deployed site is intended to be served at:

https://zxyandreay.github.io/followback-checker/

Deployment is handled by .github/workflows/deploy.yml on pushes to main:

  1. Check out the repository.
  2. Install Node.js 20 with npm cache enabled.
  3. Run npm ci.
  4. Run npm run build.
  5. Upload out/ as a GitHub Pages artifact.
  6. Deploy the artifact with actions/deploy-pages.

public/.nojekyll is included so GitHub Pages does not process the static export with Jekyll.

Validation

Run the repository-defined checks before committing documentation or code changes:

npm run lint
npm run test
npm run build

Current automated tests are library-focused and cover parser and username helper behavior. UI upload flows are not covered by browser integration tests.

Development Boundaries

  • Preserve the no-login, no-scraping, no-backend-upload privacy model.
  • Keep the app compatible with static export unless deployment is changed deliberately.
  • Avoid server-only Next.js features that static export cannot support.
  • Update tests and documentation when parser behavior, supported filenames, result categories, or deployment paths change.
  • See Project Context for detailed architecture and debugging notes.