# Generated Next.js application

This application was generated by
[`nextjs-boilerplate-kit`](https://github.com/Code-Huddle/nextjs-boilerplate-kit).
Its exact integrations depend on the options used during generation.

## Requirements

- Node.js 24 or newer
- npm 11 or a compatible package manager

## Start locally

```bash
npm install
cp .env.example .env.local
npm run dev
```

Open [http://localhost:3000](http://localhost:3000). Replace every placeholder
needed by the selected integrations in `.env.local`. Never commit secrets.

## Required quality gates

```bash
npm run check-types
npm run lint
npm test
npm run build
```

When Storybook is present:

```bash
npm run storybook
npm run storybook:build
```

Browser tests require Playwright's browser binaries:

```bash
npx playwright install
npm run test:e2e
```

## First customization

Replace starter identity and demo content before deploying:

- `.env.local`: public app name, description, canonical HTTPS URL, and selected
  provider configuration;
- `src/utils/AppConfig.ts`: author, keywords, locales, contact, and social links;
- `src/app/[locale]/(main)/page.tsx`: public homepage and structured data;
- `src/locales`: translated content;
- `src/app/sitemap.ts` and `src/app/robots.ts`: real public/private routes;
- `src/app/opengraph-image.tsx`: social-preview design;
- `public/llms.txt`: factual AI-readable site summary;
- `public/app-icon.svg` and favicon files: application branding;
- `src/templates/BaseTemplate.tsx`: shared application shell.

Search for remaining starter values:

```bash
rg -n "Your App|Your Team|example.com|your-|replace-with|FIXME|TODO" . \
  -g '!node_modules' -g '!.next'
```

## Security baseline

- Generic ORM and email demo APIs are starter code and are not automatically
  authenticated or owner-scoped. Payment routes enforce their protocol-level
  server boundaries but still need product-specific authorization decisions.
- Add product-specific authentication and authorization wherever your real
  feature needs it.
- Supabase uses the SSR client and server-validated claims. Roles come only from
  trusted `app_metadata`, never user-editable metadata or a role cookie.
- Stripe prices, amounts, customer identity, plan mapping, and redirect URLs are
  server-controlled. Webhooks verify the raw-body Stripe signature.
- Auth.js uses OAuth/server sessions; no hard-coded credential backend is
  included.
- Default response headers disable MIME sniffing and framing and restrict
  referrer and device-feature leakage.

This is a starter boundary, not the complete policy for an unknown product. Add
application-specific authorization, validation, tenant isolation, rate limits,
RLS, abuse prevention, audit logs, backups, monitoring, and incident procedures.

Reviewed dependency lifecycle scripts are version-pinned in
`package.json#allowScripts`, ready for npm's deny-by-default policy. After any
dependency update, run `npm approve-scripts --allow-scripts-pending --json` and
review new scripts instead of allowing all scripts.

## Supabase notes

If Supabase is selected:

- expose only the browser-safe publishable key through `NEXT_PUBLIC_*`;
- enable RLS for every table exposed by the Data API;
- write owner/role policies for the real schema;
- use both `USING` and `WITH CHECK` for owner-scoped updates;
- assign `app_metadata.role` from a trusted admin workflow only;
- refresh the user's JWT after changing app metadata;
- do not publicly cache authenticated responses that may refresh cookies.

The browser auth navigation tolerates missing Supabase configuration so an
unconfigured project can build, but sign-in still requires real values. With
role support, new accounts are `user` by default. Set `app_metadata.role` to
`admin` only through a trusted Dashboard/server workflow and have the user sign
in again. The generated role flow sends admins to `/admin`, other users to
`/user`, and protects `/admin`, `/user`, and `/dashboard`. Without roles,
successful sign-in goes to `/dashboard` when that module exists and `/`
otherwise. Auth.js uses the same dashboard-or-home redirect.

## Stripe notes

If Stripe is selected, create test-mode products/prices and configure the
server-side price IDs. Forward signed events locally with:

```bash
stripe listen --forward-to localhost:3000/api/stripe/webhook
```

Before fulfillment, persist processed event IDs and implement idempotent,
retry-safe handling for the event types your product treats as authoritative.

## SEO and discoverability

The application includes canonical and localized alternate URLs, robots rules,
a localized sitemap, Open Graph/Twitter metadata, a generated 1200×630 social
image, JSON-LD, web manifest, icons, and `llms.txt`.

Set `NEXT_PUBLIC_APP_URL` to the deployed HTTPS origin or those URLs will be
wrong. Add every real public route to the sitemap and exclude private/utility
routes from crawling. Validate the deployed site with structured-data, social
card, performance, accessibility, and search-console tools.

Metadata cannot guarantee rankings or AI-platform inclusion. Useful original
content, crawlable navigation, semantic structure, performance, trusted links,
and accurate factual documentation remain essential.

## Main commands

| Command | Purpose |
| --- | --- |
| `npm run dev` | development server |
| `npm run build` | optimized production build |
| `npm start` | serve the production build |
| `npm run check-types` | strict TypeScript validation |
| `npm run lint` | lint the complete project |
| `npm run lint:fix` | apply lint fixes |
| `npm test` | unit/component tests |
| `npm run test:e2e` | Playwright tests |
| `npm run clean` | remove build/test output |
| `npm run build-stats` | bundle-analyzed build |
| `npm run generate:component` | scaffold a component |

## Project structure

```text
src/
├── app/          # routes, APIs, metadata files, proxy integration
├── components/   # application and reusable UI components
├── libs/         # environment, i18n, query, and provider configuration
├── locales/      # translation messages
├── templates/    # shared page shells
├── utils/        # app configuration and helpers
└── validations/  # input schemas
```

Optional modules can add auth configuration, database schemas/clients, payment
routes, service-worker assets, Storybook, Sentry, and Docker files.

## Before production

- [ ] Replace every placeholder, demo link, and starter brand asset.
- [ ] Run all quality gates in a clean CI environment.
- [ ] Store and rotate secrets through the deployment platform.
- [ ] Review every API route for product-specific authorization and validation.
- [ ] Apply reviewed database migrations, indexes, backups, and least privilege.
- [ ] Test Supabase RLS/roles or Stripe webhook lifecycle if selected.
- [ ] Confirm OAuth callbacks, email-domain authentication, and Sentry scrubbing.
- [ ] Validate canonical URLs, robots, sitemap, social cards, and structured data.
- [ ] Add real accessibility, performance, E2E, logging, alerting, and rollback
  coverage.
- [ ] Review dependency licenses and create an SBOM for the deployed build.

## License

MIT. This generated project contains code derived from third-party open-source
work. Preserve [LICENSE](LICENSE) and
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), and review the licenses of
dependencies and any additional assets you introduce.