# STACK.md

- `STACK.md` defines the approved technology stack for the project.


## Purpose and versioning

Approved technology stack for the **SHAPE Framework documentation website**. This is a simple, content-first, multilingual site.

- Select recent compatible **stable** releases when implementation begins.
- Record exact dependency versions in `package.json` and the chosen lockfile, not in this document.
- Update this file whenever an approved technology choice changes.

## Core stack

- **Next.js** with the **App Router**
- **React**
- **TypeScript**, with strict type checking
- Node.js LTS for development, build, and production runtime
- Package manager: **pnpm** (single lockfile)

## Rendering and Deployment

- **Next.js App Router** with Node.js runtime deployment.
- Prefer static prerendering for pages whose content is available at build time.
- Use React Server Components by default; Client Components only where browser interactions are necessary.
- Generate supported localized routes at build time using `generateStaticParams`.
- Production deployment targets **Namecheap shared hosting using cPanel's Node.js application environment**.
- No standalone API backend, database, or persistent application sessions are required.
- The application must be compatible with the Node.js startup mechanism supported by Namecheap/cPanel.

## Styling and icons

- **CSS Modules** for component-level styles.
- **Global CSS custom properties** as design tokens for color, type, spacing and layout.
- Responsive, accessible layouts with semantic HTML.
- **Phosphor Icons, React package: `@phosphor-icons/react`.**
- **Default icon style: `weight="duotone"`** for consistent two-tone iconography.
- In Next.js Server Components, import the SSR-safe icons from **`@phosphor-icons/react/ssr`**.
- In Client Components, use the standard React package where needed.
- Import named icons individually; avoid wildcard imports and unnecessary icon-library wrappers.
- Use the icon's `currentColor`/CSS-based styling where possible. Decorative icons should not receive redundant accessibility labels; meaningful icons need localized accessible text.
- No Tailwind CSS or other component framework by default. Introduce only with a specific, approved reason.

Example usage:

```tsx
import { BookOpenIcon } from '@phosphor-icons/react/ssr';

export function SectionIcon() {
  return <BookOpenIcon weight="duotone" size={28} aria-hidden="true" />;
}
```

## Content and Framework Documentation

- **YAML (`.yaml`)** for localized page content, metadata, headings, labels, and structured content sections.
- **Markdown** within designated YAML fields for long-form text, including headings, paragraphs, lists, links, tables, and code examples.
- **React** for content rendering and presentation.
- **TypeScript** for application logic and typed content models.
- No MDX or executable JSX within content files.
- No CMS, database, editorial API, or remote content-fetching dependency in the initial version.
- Diagrams are optimized static assets with editable, version-controlled sources.
- **Mermaid** for source-controlled technical diagrams, including workflows, architecture, and process diagrams.
- Render diagrams as static SVG assets at build time.

## Internationalization

- Supported locales: **`en`, `es`, `de`**.
- Translation structure: **`i18n/<locale>/<page>.yaml`**, supporting nested directories for nested pages.
- **`i18n/<locale>/common.yaml`** contains shared interface text.
- All page-specific copy and SEO metadata, including long-form sections, belong in the page's own YAML file.
- **`i18n/config.ts`**: Locale types, default language, canonical route IDs, and URL helpers.
- **`i18n/dictionaries.ts`**: Typed, server-only content registry and loader.
- All supported languages share the same React rendering components and structured-content schema.
- Default English URLs are unprefixed (e.g., `/organization`); localized counterparts use `/es/organization` and `/de/organization`.
- Explicit route mapping and statically generated localized pages; no middleware-based locale detection.
- Language switcher, localized page metadata, canonical URLs, `hreflang` alternates, and multilingual sitemap.
- No automatic English fallback for missing translations; incomplete content must fail validation.
- No dedicated runtime i18n framework initially.

## Testing and developer tooling

- **ESLint** — Linting and static code analysis.
- **Prettier** — Code formatting.
- **TypeScript (strict mode)** — Static type checking.
- **Vitest** — Unit and component testing.
- **React Testing Library** — React component testing.
- **Playwright** — Browser-based functional, end-to-end, and visual regression testing.
- **Node.js scripts** — Localization and route-integrity validation.
- Required release checks: lint, typecheck, i18n validation and static production build.

## Hosting

- **Primary hosting target:** Namecheap shared hosting with cPanel Node.js application support.
- Run the Next.js application using the hosting environment's supported Node.js startup configuration.
- Serve prerendered pages where possible.
- Use the configured public site origin for canonical URLs and sitemap generation.
- Do not introduce hosting-specific application services unless required.

## Explicitly out of scope

- Databases and ORMs.
- Authentication, user accounts and session management.
- API servers, contact form submission services and transactional email.
- External CMS or remote editorial storage.
- Audience-specific duplicate content trees (leaders/business/technical) in the initial version.
- Production operational tooling unrelated to hosting the website.
## Approved content pipeline and runtime decisions

The user approved these supporting libraries for the website implementation:

- `yaml`: parse local localized content files.
- `react-markdown` and `remark-gfm`: safe Markdown rendering, including tables.
- `rehype-highlight` and `highlight.js`: syntax highlighting in documentation examples.
- `@mermaid-js/mermaid-cli`: generate static SVG diagrams during the build.
- `tsx`: execute typed build and content-validation scripts.

Use **Node.js 24 LTS** for development, builds, and production to satisfy the installed toolchain's engine requirements. Exact compatible versions are recorded in `package.json` and `pnpm-lock.yaml`. ESLint 9 and TypeScript 6 are selected for compatibility with the Next.js ESLint plugins (which do not yet declare support for ESLint 10/TypeScript 7); exact versions remain in the manifest.

Use system sans-serif and monospace fonts through design tokens; no external font dependency is required. The reusable primitives listed in `DESIGN.md` are implemented locally with the approved React/CSS stack. The Namecheap/cPanel startup adapter is `server.js`; deployment preparation is documented in `docs/DEPLOYMENT.md`.

Use `next.config.mjs` with JSDoc typing for the Next.js configuration. Loading production configuration must not require SWC/native compiler bindings or runtime TypeScript transpilation. The application remains TypeScript; this configuration-file format avoids the GLIBC compatibility failure observed on the Namecheap account without adding dependencies or changing the runtime architecture.