Development

Follow these steps to install and run the Rasuke Next.js project (rasuke-nextjs-dev).

---

Requirements

• Node.js 18.18+ or 20+ (enforced by engines in package.json)
• npm (comes with Node)

Install dependencies

Open a terminal in the rasuke-nextjs-dev folder, then run:

npm install

Start the dev server

npm run dev

Open http://localhost:3000. predev runs npm run tokens automatically so the CSS variables stay in sync with tokens/tokens.json.

Useful scripts

• npm run tokens — rebuild design tokens from tokens/tokens.json into src/styles/abstracts/_tokens.generated.scss
• npm run dev — Next.js dev server on port 3000 (predev runs tokens)
• npm run build — production build and static export to out/ (prebuild runs tokens)
• npm run start — kept for a server build; with output: "export" serve out/ with a static server instead
• npm run lint — ESLint (eslint-config-next core-web-vitals + TypeScript rules)

Project anatomy

• src/app — App Router routes. Each folder holds a page.tsx; src/app/page.tsx is the home page. There is no separate pages/ directory.
• src/components — layout (chrome), sections (page blocks), elements (shared UI), effects (client motion mount).
• src/data — one JSON file per section, plus site.json and the chrome config files.
• src/effects — vanilla GSAP / Three.js modules, imported only on the client.
• src/styles — SCSS entry (main.scss), abstracts, base, layout, components, and per-section partials.
• tokens/tokens.json — the only place to add or change design values.
• public/assets — images, fonts, video, and the vendored color-modes.js.

Static export

next.config.ts sets output: "export" and disables the Image Optimization server (images.unoptimized), which is required for an export. The build writes a complete static site to out/.

npm run build
npx --yes serve out

Deploy the out/ folder to Cloudflare Pages (build command npm run build, output directory out) or any static host. See Local Preview for the full checklist.

package.json (excerpt)

{
  "name": "rasuke-nextjs-dev",
  "version": "1.0.0",
  "private": true,
  "engines": {
    "node": ">=18.18.0"
  },
  "scripts": {
    "tokens": "node scripts/build-tokens.mjs",
    "predev": "npm run tokens",
    "dev": "next dev",
    "prebuild": "npm run tokens",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
  },
  "dependencies": {
    "glightbox": "^3.3.1",
    "gsap": "^3.15.0",
    "next": "16.3.6",
    "react": "19.2.8",
    "react-dom": "19.2.8",
    "three": "^0.184.0"
  },
  "devDependencies": {
    "@types/node": "^20",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "eslint": "^9",
    "eslint-config-next": "16.3.6",
    "sass": "^1.105.0",
    "typescript": "^5"
  }
}

next.config.ts

import type { NextConfig } from "next";
import path from "node:path";

const nextConfig: NextConfig = {
  // Static HTML export for Cloudflare Pages demo hosting
  output: "export",
  sassOptions: {
    includePaths: [path.join(process.cwd(), "src/styles")],
    silenceDeprecations: ["import", "legacy-js-api"],
  },
  images: {
    // Required with output: "export" (no Image Optimization server)
    unoptimized: true,
  },
};

export default nextConfig;

Code conventions

• Import with the @/ alias (@/components/…, @/data/…, @/lib/…) — configured in tsconfig.json.
• Keep the HTML master's BEM class names. Ports must not rename classes or invent a second design system.
• Section components stay Server Components unless they need browser APIs. Motion lives in src/effects and is booted by the client-only bootstrap.
• Never edit _tokens.generated.scss — change tokens/tokens.json and run npm run tokens.
• No CSS framework and no Tailwind. Layout is SCSS Grid / Flexbox with token-driven values.