02 / 15 · Project map & commands

Project map and commands

All editable paths and commands in these guides are relative to the source/ folder in the buyer bundle: the folder containing package.json. The outer static-export/ folder is a prebuilt sample, not the place to edit TypeScript files.

Folder map

source/
  src/
    app/
      globals.css        Layout, responsive rules and theme tokens
      [[...lang]]/       Root entry and statically generated language pages
        layout.tsx       Document/viewport and localized metadata wiring
        page.tsx         Renders root and each configured language page
      not-found.tsx      Missing-page content
      global-not-found.tsx Default-language exported 404 document
    components/          Landing sections, locale provider and controls
      document-frame.tsx Font, language/direction, prepaint setup and preview-image preload
      brand-logo.tsx     Configured local brand image
      product-preview.tsx Configured video or alternative image gallery
      product-video.tsx  Native video with themed bottom controls and fallback
      media-preview.tsx  Shared responsive image treatment
      testimonials.tsx   Quote navigation and optional autoplay
      newsletter.tsx     Section/dialog preview, native Kit, embedded Kit or endpoint form
      kit-newsletter.tsx Forma-styled Kit signup fields and required marketing choice
      kit-submission.tsx Shared asynchronous signup state and hosted fallback
      kit-attribution.tsx Provider-issued Built with Kit attribution for native forms
      demo-access-form.tsx Demo access with optional Kit mailing-list permission
    config/
      site.ts            Main shared brand/media/cards/links/signup settings
      sections.ts        Section types; not another settings entry point
      preview.ts         Product media types; edit values in site.ts
      cookies.ts         Theme/language storage settings and privacy link
      languages.ts       Exactly two language entries and default code
      security.ts        HSTS settings and reviewed extra CSP origins
    content/
      primary.ts         Primary language text, initially English
      secondary.ts       Secondary language text, initially Greek
      types.ts           Common content shape
    assets/              Bundled local Manrope font
    lib/                 Content, language, metadata, theme and UI helpers
      form-validation.ts Shared browser-validity checks for enhanced local forms
      newsletter.ts      Newsletter/demo-access public configuration validation
      kit-native.ts      Lazy Kit public-handler adapter, not an account API client
      kit-request-lock.ts Shared page-local request lock for embedded/native Kit signup
      kit-provider-guards.ts Shared top-layer wrapper retaining Kit verification UI/callbacks
    styles/
      marketing.css      Reusable media, cards, gallery and video controls
      newsletter.css     Newsletter and demo-access form/dialog details
      branding.css       Logo variants and social links
  public/                Favicon, social image and local product media
    product/             WebP samples, editable SVG originals, demo video and captions
  docs/                  HTML guides, Markdown originals and licences
  scripts/               Development, build, preview, docs and ZIP helpers
    serve.mjs            Loopback production preview with text gzip and video ranges
    media-range.mjs      Byte-range helper imported by local serve.mjs
    text-response.mjs    Text-response gzip negotiation imported by serve.mjs
    site-files.mjs       Public-origin sitemap, robots and font-preload post-build step
    font-preload.mjs     Missing single-font preload helper imported by site-files.mjs
    security-headers.mjs Export policy generation, validation and preview header helper
  tests/                 Automated checks
  package.json           Commands and compatible Node/npm versions
  AGENTS.md              Short entry point for agents configuring the project
  package-lock.json      Locked dependency versions
  next.config.mjs        Static export configuration
  .env.example           Safe public site URL example
  NOTICE.txt             Publisher and ownership notice
  LICENSE.txt            Complete commercial template licence

node_modules/, .next/ and out/ are generated when you install or build. They are not source files. Edit src/ and public/, then rebuild; editing the generated out/ directly would lose those changes on the next build.

What do you want to change?

TaskMain fileImportant companion check
Product name, logo and brand accent colorssrc/config/site.tsUse name and brand; update translated copy and assets too.
Hero, navigation, footer and all UI textsrc/content/primary.ts and secondary.tsEdit both languages and preserve keys/placeholders.
Header and hero conversion actionssrc/config/site.tsTest destinations at phone and desktop widths.
Get started demo-access labels and success linkBoth content files under dialog; siteSettings.dialogActionDefault local simulation; optional mailing-list permission uses demoAccess; continuation is a public link.
Features, gallery, testimonials and pricing copyBoth content files under sectionsMatch count/order with shared arrays and publish truthful claims.
Shared cards, gallery, quotes and pricing settingssrc/config/site.ts under sectionsAdd matching text in both dictionaries; prices use locale formatting.
Product screenshots or videosrc/config/site.ts under previewLocal files in public/; UI captions/alt text in both dictionaries, optional video track shared.
Email signup placement/mode, Kit forms or endpointsrc/config/site.ts under newsletterRead EMAIL; supply your own account/receiver and privacy policy.
Newsletter wording and consent labelBoth content files under newsletterNative Forma labels/status are here; embedded provider fields are edited in Kit.
Social linkssrc/config/site.ts under socialLinksEmpty array hides group; verify every real URL and label.
Language codes/names/direction/defaultsrc/config/languages.tsPreview both generated URLs and font coverage.
Cookie copyBoth content files under cookiesKeep inventory accurate in both languages.
Cookie privacy link/settingssrc/config/cookies.tsTest allow, decline, withdrawal, expiry and root behaviour.
Preference banner and dialogsrc/components/cookie-controls.tsxKeep keyboard/focus behaviour and accurate storage inventory.
Consent cookie parsing and persistencesrc/lib/cookies.tsKeep validity checks and theme/language storage gating aligned.
Deeper surface colors, sizing and layoutsrc/app/globals.css and src/styles/Use the stylesheet map above; brand accent fields are in site.ts. Check themes and contrast.
Visible logo filesiteSettings.brand.logo plus public/Optional dark image, dimensions and adjacent name are configurable.
Browser faviconsiteSettings.brand.favicon plus public/Separate from visible logo; initial file is public/icon.svg.
Social sharing artworksiteSettings.brand.socialImage and assetSet path and actual width/height; initial size is 1200×630.
Titles/descriptionsBoth content filesMetadata structure: src/lib/metadata.ts. Image dimensions: brand.socialImage in site.ts.
Real public site URL.env.local or host build variableSet NEXT_PUBLIC_SITE_URL and rebuild.
HSTS and extra CSP service originssrc/config/security.tsRebuild, check the generated policy and apply it on the real HTTPS host; see DEPLOYMENT.
Overall page ordersrc/components/landing-page.tsxMaintain a logical heading and navigation order.
Below-hero section ordersrc/components/landing-sections.tsxRemove links to removed sections.

These are code-editing locations. Forma does not include an admin panel or visual content editor.

For work delegated to a coding agent, start with AGENTS.md and the Agent customization manual. It explains how to turn a client brief into configuration/content/assets changes, validate both languages and hand over the result without confusing local demonstrations with real collection or account features.

Everyday commands

Run commands from the project folder. On Windows use npm.cmd instead of npm if PowerShell blocks npm.ps1.

CommandPurpose and expected result
npm ciInstall locked dependencies. Needs internet; wait for success before other commands.
npm run devStart a development server at http://127.0.0.1:3100; saved source edits refresh the page.
npm run buildCreate the optimized static export in out/.
npm run security:checkVerify the exported HTML matches its generated security manifest and static-host header recipe.
npm run startPreview the existing out/ locally; build first and stop the dev server.
npm run formatFormat editable project files with Prettier. Review changes before saving them to version control.
npm run format:checkCheck formatting without rewriting files.
npm run lintCheck JavaScript, TypeScript and React usage with ESLint.
npm run typecheckCheck TypeScript configuration and component contracts without emitting code.
npm testRun the included automated tests.
npm run languages:checkValidate both language definitions and complete content dictionaries.
npm run checkValidate languages/content and docs, formatting, lint, TypeScript, tests, production build and its security artifacts.
npm run docsRegenerate offline HTML after editing the Markdown guide sources.
npm run docs:checkCheck generated guides match their Markdown sources and local links resolve.
npm run packageCreate a source/docs/static-export ZIP from a completed build. This is optional for your own site deployment.

Only one process can listen on a given local port at a time. Stop your own running dev or preview terminal with Ctrl+C before starting the other.

Source, build and hosting

The process is:

Edit src/content/, src/config/ and public/
        ↓
npm run check
        ↓
Review out/ with npm run start
        ↓
Upload the contents of out/ to static hosting

next.config.mjs enables output: 'export' and trailingSlash: true. The landing page's controls run in the browser; your published export does not need a Node.js application server or database.

Both configured languages are exported as directory pages. The root entry renders the default and optionally follows a permitted remembered language; a direct language URL wins. Metadata uses the public origin when set. The build-generated sitemap.xml and robots.txt use that origin, or the local preview origin if it is absent. Set the final origin before publishing. See Languages and SEO.

Landing documents preload the configured video poster, or the first product screenshot when it has no separate darkSrc. The selected screenshot loads eagerly; later card/workflow media and gallery thumbnails are lazy-loaded. The exported missing-page document keeps its default-language content and preference controls without requesting a product-media preload. These choices do not preload the MP4 or enable autoplay.

After a successful build, scripts/next.mjs copies LICENSE.txt, NOTICE.txt, THIRD-PARTY-NOTICES.txt and MANROPE-LICENSE.txt into out/. Keep those files beside the compiled export. The packaging helper checks their bytes against the canonical source documents rather than silently replacing a stale build's notices.

The build also creates out/forma-security.json and out/_headers from the exported HTML, collection modes, configured asset URLs and src/config/security.ts. The manifest records document-specific script hashes/policies; the static-host recipe uses the build's combined inline-script hash list. npm run start checks each requested HTML document against its recorded digest and applies its CSP. It serves the existing build rather than checking edited source settings or the full _headers file at startup. Run npm run security:check to compare the artifacts with current settings. Ordinary HTTP localhost deliberately has no HSTS. The files do not configure an arbitrary production host automatically; follow HSTS and Content Security Policy for the HTTPS and host-header steps. Rebuild after configuration or HTML changes rather than editing generated hashes.

The product media and demo-access form do not become a SaaS application by changing labels. The header's default kind: 'demo' opens local name/email preview, validates locally and reveals a configurable public link without saving or transmitting input. demoAccess.mode: 'kit' can independently add optional marketing permission and background signup through a separate Kit Form. Unchecked continues without a Kit request; checked does not make the continuation depend on the provider. Closing resets demo access. This is not authentication or protected access; real signup/login links can lead to the client's existing application.

Newsletter uses a page section by default. With enabled newsletter.placement: 'dialog', exact #newsletter CTA/navigation links open signup; kind: 'demo' remains independent. Closing/reopening preserves a newsletter instance until the shared dialog switches purpose, the page changes or reloads. kit-native shows Forma's fields immediately and loads Kit only after a valid consented submission. kit embeds the provider-designed Form automatically by default, with optional kitLoad: 'interaction'; endpoint uses a compatible receiver's ordinary POST. No receiving backend, account API secrets or database are included. See Customization, Email signup and Kit and Build and deploy.

Keep private files private

Files in public/ are publicly downloadable. Values prefixed NEXT_PUBLIC_ are public build settings; never put passwords, private API keys or tokens there.

Keep real .env files, credentials, dependency folders and build caches out of public source archives. Preserve the supplied lockfile and third-party licence notices. The safe .env.example may be shared because it contains only an empty public site URL placeholder.