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.
On this page
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?
| Task | Main file | Important companion check |
|---|---|---|
| Product name, logo and brand accent colors | src/config/site.ts | Use name and brand; update translated copy and assets too. |
| Hero, navigation, footer and all UI text | src/content/primary.ts and secondary.ts | Edit both languages and preserve keys/placeholders. |
| Header and hero conversion actions | src/config/site.ts | Test destinations at phone and desktop widths. |
| Get started demo-access labels and success link | Both content files under dialog; siteSettings.dialogAction | Default local simulation; optional mailing-list permission uses demoAccess; continuation is a public link. |
| Features, gallery, testimonials and pricing copy | Both content files under sections | Match count/order with shared arrays and publish truthful claims. |
| Shared cards, gallery, quotes and pricing settings | src/config/site.ts under sections | Add matching text in both dictionaries; prices use locale formatting. |
| Product screenshots or video | src/config/site.ts under preview | Local files in public/; UI captions/alt text in both dictionaries, optional video track shared. |
| Email signup placement/mode, Kit forms or endpoint | src/config/site.ts under newsletter | Read EMAIL; supply your own account/receiver and privacy policy. |
| Newsletter wording and consent label | Both content files under newsletter | Native Forma labels/status are here; embedded provider fields are edited in Kit. |
| Social links | src/config/site.ts under socialLinks | Empty array hides group; verify every real URL and label. |
| Language codes/names/direction/default | src/config/languages.ts | Preview both generated URLs and font coverage. |
| Cookie copy | Both content files under cookies | Keep inventory accurate in both languages. |
| Cookie privacy link/settings | src/config/cookies.ts | Test allow, decline, withdrawal, expiry and root behaviour. |
| Preference banner and dialog | src/components/cookie-controls.tsx | Keep keyboard/focus behaviour and accurate storage inventory. |
| Consent cookie parsing and persistence | src/lib/cookies.ts | Keep validity checks and theme/language storage gating aligned. |
| Deeper surface colors, sizing and layout | src/app/globals.css and src/styles/ | Use the stylesheet map above; brand accent fields are in site.ts. Check themes and contrast. |
| Visible logo file | siteSettings.brand.logo plus public/ | Optional dark image, dimensions and adjacent name are configurable. |
| Browser favicon | siteSettings.brand.favicon plus public/ | Separate from visible logo; initial file is public/icon.svg. |
| Social sharing artwork | siteSettings.brand.socialImage and asset | Set path and actual width/height; initial size is 1200×630. |
| Titles/descriptions | Both content files | Metadata structure: src/lib/metadata.ts. Image dimensions: brand.socialImage in site.ts. |
| Real public site URL | .env.local or host build variable | Set NEXT_PUBLIC_SITE_URL and rebuild. |
| HSTS and extra CSP service origins | src/config/security.ts | Rebuild, check the generated policy and apply it on the real HTTPS host; see DEPLOYMENT. |
| Overall page order | src/components/landing-page.tsx | Maintain a logical heading and navigation order. |
| Below-hero section order | src/components/landing-sections.tsx | Remove 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.
| Command | Purpose and expected result |
|---|---|
npm ci | Install locked dependencies. Needs internet; wait for success before other commands. |
npm run dev | Start a development server at http://127.0.0.1:3100; saved source edits refresh the page. |
npm run build | Create the optimized static export in out/. |
npm run security:check | Verify the exported HTML matches its generated security manifest and static-host header recipe. |
npm run start | Preview the existing out/ locally; build first and stop the dev server. |
npm run format | Format editable project files with Prettier. Review changes before saving them to version control. |
npm run format:check | Check formatting without rewriting files. |
npm run lint | Check JavaScript, TypeScript and React usage with ESLint. |
npm run typecheck | Check TypeScript configuration and component contracts without emitting code. |
npm test | Run the included automated tests. |
npm run languages:check | Validate both language definitions and complete content dictionaries. |
npm run check | Validate languages/content and docs, formatting, lint, TypeScript, tests, production build and its security artifacts. |
npm run docs | Regenerate offline HTML after editing the Markdown guide sources. |
npm run docs:check | Check generated guides match their Markdown sources and local links resolve. |
npm run package | Create 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.