Skip to content
Pinchana Docs

Web development

Pinchana Web is a Bun-managed Next.js application. The current repository uses Bun 1.3.14, Next.js 16.2.10, React 19.2.4, TypeScript 5, and Tailwind CSS 4.

Install and run

Section titled “Install and run”
Terminal window
git clone https://github.com/Pinchana/pinchana-web.git
cd pinchana-web
bun install --frozen-lockfile
cp .env.example .env.local
bun run dev

Open http://localhost:3000.

predev and prebuild synchronize the locally bundled FFmpeg WebAssembly assets, so do not bypass the repository scripts when testing media conversion.

Minimum local environment

Section titled “Minimum local environment”
PINCHANA_API_URL=http://localhost:8080
NEXT_PUBLIC_TURNSTILE_SITE_KEY=REPLACE_WITH_PUBLIC_SITE_KEY

PINCHANA_API_URL is server-only. The current Web client expects the API to expose POST /v1/web/scrape.

For local Turnstile UI work, Cloudflare’s documented always-pass test site key can be used with the corresponding API-side test secret. Production must use the real hostname-bound site/secret configuration.

Custom-instance development

Section titled “Custom-instance development”

Custom API connections are enabled only when PINCHANA_INSTANCE_PUBLIC_KEY contains a valid Ed25519 public key. Production custom origins require HTTPS. Development builds can accept local HTTP origins for testing.

The private certificate-signing key never belongs in the Web repository or Web environment.

Monitoring

Section titled “Monitoring”

Monitoring is explicitly build-time gated:

SENTRY_MONITORING_ENABLED=false
NEXT_PUBLIC_SENTRY_DSN=
NEXT_PUBLIC_SENTRY_ENVIRONMENT=development

When monitoring is disabled, an externally supplied DSN is ignored. Enabling monitoring requires a rebuild. SENTRY_AUTH_TOKEN, when used for source-map upload, must be supplied as a BuildKit secret rather than a public environment variable.

Checks

Section titled “Checks”

Run all repository checks before merging:

Terminal window
bun run test
bun run lint
bun run build

The production build uses next build --webpack and then verifies the Sentry build configuration.

Development boundaries

Section titled “Development boundaries”
  • Browser code must call same-origin /api/... routes, not PINCHANA_API_URL directly.
  • Do not add API machine credentials to Web.
  • Do not expose server-only values via NEXT_PUBLIC_....
  • Keep authenticated media on the same-origin media proxy rather than the Next image optimizer.
  • DLP cookie plaintext must remain in browser memory and the ephemeral worker boundary; the BFF should only forward ciphertext.
  • Preserve the custom-instance certificate verification path instead of accepting arbitrary origins.

Internationalization

Section titled “Internationalization”

English and Ukrainian are active. Application catalogs live in messages/app, legal catalogs in messages/legal, and locale metadata is in i18n/config.ts.

See the translation guide before changing message sources, ICU arguments, or activating a new legal locale.