ClueCircuit

Documentation

Escape room & group events website template for Next.js 16. Five venue demos with working visit planners, exported as a static site you can host anywhere.

1.Welcome

Thank you for choosing ClueCircuit. This guide covers everything from installing the template to putting a finished venue website online. No previous Next.js experience is assumed: every step shows the exact command or file to change.

If something is unclear, see Troubleshooting & FAQ first, then contact us through Support. We are happy to help.

This guide works offline. Open documentation/index.html from the download in any browser, or print it (or save it as PDF) for reference.

2.What is included

ClueCircuit is one Next.js project with five complete venue demos and a showcase page that compares them. Each demo has its own brand, eight designed pages, a detail page for every room or game, and a planning journey a visitor can finish on a phone.

DemoFolderBusiness typePlanning journey
The Puzzle Clubsrc/venues/puzzle-clubFamily & birthday venueAge-based room finder → party package builder → enquiry review
Night Signal Roomssrc/venues/night-signalBoutique escape venueGroup details → room assignments → shareable, printable itinerary
After Hourssrc/venues/after-hoursLate-night horror & live theatreScare-level finder → actor & sensory guide → late-session picker
Fieldwork Gamessrc/venues/fieldwork-gamesCorporate team-buildingEvent brief → schedule comparison → quote request
Puzzle Dispatchsrc/venues/puzzle-dispatchMobile games at the client’s venueService-area checker → venue setup check → event request

The download contains:

  • The full Next.js 16 project in TypeScript, with package-lock.json for exact dependency versions.
  • Sample venue data for all five demos, in plain data files you edit.
  • Ten self-hosted font families with their licences.
  • Labelled placeholder images, sized for every image slot.
  • Unit tests for the planning rules and browser tests for every journey.
  • This documentation.
How bookings work: there is no database, payment system or mail server. Planners run in the browser. Booking buttons hand the visitor to your existing booking system, and enquiry forms post to an endpoint you control. Out of the box, forms run in a clearly labelled demo mode that sends nothing. See Booking handoff and Enquiry forms.

3.Quick start

  1. Install — open the ClueCircuit folder in a terminal:
    npm ci
  2. Preview — start the development server and open http://localhost:3000:
    npm run dev
  3. Pick one venue — create .env.local next to package.json with the demo closest to your client (see Choose a demo):
    NEXT_PUBLIC_DEMO=puzzle-club
  4. Make it yours — edit src/venues/<venue>/data.ts (name, rooms, prices, sessions, FAQ), replace the images in src/media/<venue>/ and set your booking link.
  5. Publish — build, then upload the contents of the out/ folder to any web host:
    npm run build

4.Requirements

  • Node.js 22.13 or later in the 22.x line, or any Node.js 24.x, with npm. Tested with Node.js 24.21.0 / npm 11.19.0 and Node.js 22.13.0 / npm 10.9.2. Check yours with node -v.
  • A code editor, for example Visual Studio Code.
  • Any static web host for the live site (see Host-by-host guides). No Node.js server is needed in production.

Built with Next.js 16.4.6, React 19.3.1 and TypeScript 6.0.3.

5.Install & local preview

  1. Unzip the download and open the ClueCircuit folder in a terminal.
  2. Install the dependencies. npm ci uses the included lockfile, so you get exactly the tested versions:
    npm ci
  3. Start the development server:
    npm run dev
  4. Open http://localhost:3000. Changes you save in src/ appear automatically.

Sample dates

Sample sessions are generated from today’s date, so the demo never looks out of date. To see the exact worked examples (Friday 20 November 2026 and so on), add ?clock=fixture to any address, for example http://localhost:3000/puzzle-club/party/finder/?clock=fixture. Use ?clock=live to switch back.

6.Build the static site

npm run build      # creates the out/ folder: this is your whole website
npm run serve      # previews out/ at http://localhost:4173

Upload the contents of out/ to your host. Every page is a real HTML file, so the site works on any static host.

Quality checks

npm run typecheck   # TypeScript
npm run lint        # ESLint
npm test            # planning-rule unit tests (capacities, prices, times)
npm run check       # all of the above, then a build
npm run e2e         # browser tests (run "npx playwright install" once first)

7.Choose a demo (single-venue build)

Most websites need one venue, not five. One setting, NEXT_PUBLIC_DEMO, chooses what is built. Create a file called .env.local next to package.json:

# .env.local
NEXT_PUBLIC_DEMO=puzzle-club
ValueResult
showcase (default)The showcase at / and all five demos under /puzzle-club/, /night-signal/ and so on, each with an “All venues” link.
puzzle-club, night-signal, after-hours, fieldwork-games, puzzle-dispatchOnly that venue is built. Its homepage opens at / and its pages lose the prefix (for example /adventures/). The showcase and the other four venues, including their code and images, are left out of the website.

Run npm run build again after changing the value. An unknown value stops the build with a clear message.

To remove the other venues from your project as well, delete their folders in src/venues/, src/media/ and src/app/, then remove their lines from src/venues/registry.ts.

8.Project structure

ClueCircuit/
  documentation/             this guide
  public/                    favicon
  scripts/                   local server, link checker, test helpers
  tests/                     unit tests (Vitest) and browser tests (Playwright)
  src/
    app/[[...path]]/page.tsx the site root: the showcase, or every page of a single-venue build
    app/<venue>/[[...path]]/page.showcase.tsx
                             that venue's pages in the showcase build
    app/not-found.tsx        accessible 404 page
    core/                    shared logic: dates and times, money, validation, enquiries, config
    ui/                      shared components: form fields, stepper, tabs, accordion, icons
    showcase/                the demo chooser (content.ts holds its text)
    venues/
      registry.ts            which venues a build contains
      types.ts               the contract every venue follows
      <venue>/data.ts        rooms or games, capacities, prices, sessions, copy, FAQ (start here)
      <venue>/planner.ts     planning rules (unit-tested)
      <venue>/meta.ts        name, colours and showcase card
      <venue>/index.tsx      the venue's pages, titles and descriptions
      <venue>/Shell.tsx      header, navigation, footer and logo
      <venue>/theme.css      colours, type scale and layout for that brand
      <venue>/fonts.ts       self-hosted fonts
      <venue>/pages/        one component per page
    media/<venue>/           images
    fonts/                   font files and licences

Each venue folder starts with data.ts. Comments at the top of each file explain what it holds. Some venues split their rules into extra files, for example a schedule or coverage module.

9.Rooms, games & content

All records live in the venue’s data.ts. Example for Night Signal (src/venues/night-signal/data.ts):

{
  id: "the-lighthouse",          // used in the URL /rooms/the-lighthouse/: lowercase, hyphens
  name: "The Lighthouse",
  difficulty: "beginner",
  minPlayers: 2,
  maxPlayers: 5,
  durationMin: 60,               // whole minutes
  priceFromMinor: 2500,          // £25.00: prices are in pence/cents
  tagline: "…",
  headline: "…",
  story: ["…", "…"],
  image: roomLighthouse, imageAlt: "…",
}
  1. Copy an existing record in the rooms (or games / adventures) list and change its values.
  2. Add its images to src/media/<venue>/ and import them at the top of data.ts (see Images). Set an image to null to show a tidy “Image coming soon” panel.
  3. Save. The directory, a new detail page, the filters and the planner all pick up the record automatically.

Venue name, address, email, phone, opening notes and FAQ answers are in the same file. All visible text is ordinary text in data files or page components; there are no images of text.

Keep id values stable once the site is live. Share links and booking handoffs use them.

10.Capacities, prices & rules

  • Capacity: minPlayers and maxPlayers per room, kit or game. Planners never create a team below the minimum.
  • Minimum ages (The Puzzle Club, After Hours): minAge on each record.
  • Prices: always whole numbers in minor units (2800 = £28.00). Change currency and locale in the venue object to switch currency formatting.
  • Time zone: timeZone, for example "Europe/London". “Today” and session times use the venue’s time zone, not the visitor’s.
  • Arrival buffer, setup, pack-down and kit reset times: named fields near the top of each venue’s data file.
  • Service area (Puzzle Dispatch): the list of covered postcode districts. Matching is exact, so BS1 does not match BS10.

After changing rules, run npm test. The unit tests check the worked examples; if you change the sample data on purpose, update the expected numbers in tests/unit/<venue>.test.ts.

11.Sessions & availability

Each venue’s data file defines its open weekdays, its session start times (minutes after midnight, so 975 is 4:15 PM) and sample sold-out rules. Visitors see upcoming dates generated from today. A session that ends after midnight is shown with a next-day finish.

The sample availability is illustrative. For live availability, connect your booking system with the booking handoff: the planner prepares the visit and your booking system confirms it.

12.Brand, colours & fonts

  • Colours: custom properties at the top of src/venues/<venue>/theme.css. The --cc-* properties style the shared buttons and form fields.
  • Logo: an inline SVG in the venue’s Shell.tsx (or a small logo component next to it). Replace the SVG, or swap it for an <Image>.
  • Navigation: the NAV list in Shell.tsx. Each item has a label and a venue-relative path. Keep using venueHref() so links work in both showcase and single-venue builds.
  • Fonts: fonts.ts loads self-hosted files from src/fonts/. To change a font, add its .woff2 files and licence to src/fonts/<name>/ and point fonts.ts at them. No font is loaded from a third-party server.
  • Page titles and descriptions (for search engines): the routes list in the venue’s index.tsx.
  • Showcase text (only in the showcase build): src/showcase/content.ts.

13.Images

Important: the photographs and illustrations on the live preview are for preview only and are not included in the download. Every image slot ships with a labelled placeholder of the same size and shape. Replace them with images you have the rights to use.
  1. Put your image in src/media/<venue>/. Keep the same file name to replace an image without touching code, or add a new file.
  2. Use roughly the same aspect ratio as the file you replace. src/media/<venue>/README.txt lists the size of each slot.
  3. For a new file, import it in data.ts or the page that uses it: import myPhoto from "@/media/puzzle-club/my-photo.jpg";
  4. Write meaningful imageAlt text for content images. Leave alt text empty only for purely decorative images.

Tips for fast pages: export photos as JPEG (quality 80–85) or WebP, at about twice the width they appear on screen; most slots need 1,600 px wide or less. Images below the first screen load only when the visitor scrolls to them.

Images are imported rather than linked by URL, so they keep working when the site is deployed in a sub-folder.

14.Booking handoff

Session pickers end with a “Continue to booking” button. Set the venue’s bookingUrl in data.ts:

bookingUrl: "https://bookings.example.com/your-venue",

The button links to that address and adds only non-personal choices as query parameters, for example ?room=dead-air&date=2026-11-20&time=1320. Check which parameter names your booking provider accepts, and adjust the params passed to <BookingHandoff> on that page if needed.

Without a bookingUrl, the button shows a clearly labelled “Local demo handoff — no booking made” panel.

15.Enquiry forms

Enquiry and contact forms run in demo mode by default. The visitor sees “Demo request prepared locally” and can copy or print the request. Nothing is sent and nothing is booked.

Turn on delivery

# .env.local
NEXT_PUBLIC_ENQUIRY_MODE=connected
NEXT_PUBLIC_ENQUIRY_ENDPOINT=https://your-endpoint.example.com/enquiry
NEXT_PUBLIC_ENQUIRY_TIMEOUT_MS=10000      # optional, default 10 seconds

Rebuild after changing these. A venue can use its own endpoint through enquiryEndpoint in its data.ts. To turn delivery off, remove NEXT_PUBLIC_ENQUIRY_MODE (or set it to demo) and rebuild.

A static site cannot run server code, so the endpoint must be something you operate: a serverless function (Netlify, Vercel, Cloudflare), a form service, or a CRM webhook. Never put secret keys in NEXT_PUBLIC_* variables, because visitors can see them. Keep secrets on the endpoint’s side.

What the form sends

POST with Content-Type: application/json and an Idempotency-Key header. A retry after a failure reuses the same key, so your endpoint can ignore duplicates.

{
  "venue": "puzzle-club",
  "kind": "birthday-enquiry",     // contact, group-enquiry, quote-request, event-request …
  "summary": { "Date": "Saturday, 21 November 2026", "Children": "6", "Package": "Party package" },
  "contact": { "name": "…", "email": "…", "phone": "…", "message": "…" },
  "submittedAt": "2026-11-19T10:12:00.000Z",
  "idempotencyKey": "6c0e…"
}

What your endpoint should return

ResponseWhat the visitor sees
2xx with {"ok":true,"reference":"ABC123"} (reference optional)“Enquiry sent to <venue>” plus the reference, worded as an enquiry rather than a confirmed booking.
4xx with {"ok":false,"message":"…"}Your message, with every form value kept.
5xx, network error or timeoutA recoverable error. Values are kept and the visitor can try again.

Your endpoint must validate the data again, because browser checks can be bypassed. It must also allow cross-origin requests from your site: Access-Control-Allow-Origin, Access-Control-Allow-Headers: Content-Type, Idempotency-Key, and an OPTIONS response.

Test it locally

node scripts/test-receiver.mjs --port 4399     # a fake endpoint that logs requests
NEXT_PUBLIC_ENQUIRY_MODE=connected NEXT_PUBLIC_ENQUIRY_ENDPOINT=http://localhost:4399/enquiry npm run build
npm run serve

Switch the fake endpoint between outcomes with curl -X POST localhost:4399/__mode -d '{"mode":"fail"}' (modes: ok, fail, reject, slow).

16.Pages & layouts

  • Add a page: create a component in src/venues/<venue>/pages/ and add an entry to the routes list in that venue’s index.tsx (path, title, description, render). The export picks it up automatically.
  • Reorder or remove a section: edit the page component. Every section is ordinary JSX.
  • Reuse shared components: import from @/ui/primitives (NumberStepper, Tabs, Accordion, StepNav, ErrorSummary, CopyLinkButton, LiveRegion), @/ui/EnquiryForm or @/ui/BookingHandoff.
  • Change planning logic: edit the venue’s planner module and add a unit test next to the existing ones.

17.Deployment

At a domain root (https://example.com/)

npm run build

Upload the contents of out/. Make sure your host serves 404.html for unknown addresses (most static hosts do this automatically; see the guides below).

In a sub-folder (https://example.com/escape-rooms/)

# .env.local
NEXT_PUBLIC_BASE_PATH=/escape-rooms

Build, then upload the contents of out/ into the escape-rooms folder on your server. Links, images, fonts, scripts, share links and itineraries all use the sub-folder automatically. Preview it locally with npm run serve -- --base /escape-rooms and open http://localhost:4173/escape-rooms/.

Pages are exported as folders containing index.html (for example adventures/index.html), so direct links and page reloads work on ordinary static hosts.

18.Host-by-host guides

HostSettings
NetlifyConnect your repository with build command npm run build and publish directory out, or run npm run build yourself and drag the out folder onto the Netlify dashboard. Add your NEXT_PUBLIC_* values under Site configuration → Environment variables.
VercelImport the repository. Vercel detects Next.js and serves the static export. Add your NEXT_PUBLIC_* values under Project Settings → Environment Variables.
Cloudflare PagesBuild command npm run build, build output directory out. Set NODE_VERSION to 24 (or 22) in the environment variables.
GitHub PagesFor a project page (https://user.github.io/repo/) set NEXT_PUBLIC_BASE_PATH=/repo. Add an empty file named .nojekyll to the uploaded folder so the _next folder is published, or deploy with GitHub Actions.
Shared hosting (Apache / cPanel)Upload the contents of out/ to public_html (or your sub-folder) with the file manager or FTP, keeping the folder structure. Add ErrorDocument 404 /404.html to .htaccess (use /escape-rooms/404.html in a sub-folder).
Nginxtry_files $uri $uri/ $uri.html =404; and error_page 404 /404.html; in the server block.
Whichever host you use, always upload the contents of out/ with its folders intact. Do not upload the src folder or node_modules.

19.Performance

  • Static pages: every page is pre-rendered HTML, served from your host or CDN with no server work.
  • Only what a page needs: each page downloads only its own venue’s JavaScript, and a single-venue build contains no code or images from the other venues.
  • Fonts: self-hosted and loaded with font-display: swap, so text appears immediately; a page downloads only the fonts it uses.
  • Images: sized for their slots; images below the first screen load only when scrolled to. Follow the tips in Images when you add your own.
  • No third-party scripts: no analytics, trackers or external fonts are included.

Page speed depends on your host and images, so measure your own deployed site with your browser’s Lighthouse panel.

20.Privacy

  • Planner choices (group size, date, time, selected room or game) are kept in the page address, so back, reload and share links work. They are not personal data.
  • Names, emails, phone numbers, addresses and messages are never put in links, browser storage or analytics. They exist only in the open form, and are sent only when you connect an endpoint.
  • If the browser blocks storage (for example inside a preview frame), everything still works. Copy-link falls back to a selectable text box, and printing falls back to a hint.
  • The template sets no cookies and includes no analytics or third-party scripts. If you add any, update your site’s privacy notice.

21.Accessibility

The template uses semantic HTML, native form controls, labelled fields, error summaries, visible focus styles, keyboard-operable menus, tabs and accordions, reduced-motion support, and text alternatives for maps, floor plans, schedules and meters. Every page type was checked with automated tools (axe) and keyboard tests.

This is not a formal accessibility certification. When you customise the site, check your own content: alt text for new images, colour contrast after colour changes, and clear link and button wording.

22.Browser support

Supported: the current versions of Chrome, Edge, Firefox and Safari on desktop, plus Safari on iOS and Chrome on Android. Every journey is tested automatically in Chromium, Firefox, WebKit (Safari’s engine) and mobile Chromium, from 360 px phones to 1440 px desktops. Internet Explorer is not supported.

23.Troubleshooting & FAQ

Problem or questionAnswer
npm ci failsCheck that node -v shows 22.13 or later in 22.x, or any 24.x. Delete node_modules and run npm ci again.
Build stops with “NEXT_PUBLIC_DEMO is not valid”Use one of the values in Choose a demo, spelled exactly.
Pages work locally but styles or images are missing on the serverYou uploaded to a sub-folder. Set NEXT_PUBLIC_BASE_PATH to that folder and rebuild (Deployment).
Reloading a page shows the host’s own 404Upload the folder structure exactly as built; do not flatten out/.
On GitHub Pages the site has no stylesAdd an empty .nojekyll file (Host-by-host guides).
The planner shows “Loading dates…”JavaScript is disabled or blocked. The planners need JavaScript; the content pages do not.
Forms say “Demo mode”Expected until you connect an endpoint (Enquiry forms).
Enquiries fail with a network errorYour endpoint must allow cross-origin requests from your site’s domain.
The worked examples show other datesAdd ?clock=fixture to the address (Install & preview).
Does it take payments or confirm bookings?No. It prepares the visit and hands it to your booking system, or sends an enquiry to your endpoint.
Can I use it without the showcase?Yes. Build a single venue (Choose a demo); the showcase is left out.
Can I mix parts of different demos?Yes. Every venue uses the same shared components, so you can copy a page or section from one venue folder to another and adjust its styles.

24.Support

Need help? Contact us through the Support tab on the ClueCircuit item page on ThemeForest (SoftfireStudio).

Item support includes

  • Answers to questions about how the template works and how to use its features.
  • Help with reported bugs and issues in the template.
  • Help with the included third-party assets (fonts and libraries).

Item support does not include

  • Customisation or new features, such as connecting a specific booking provider or building your enquiry endpoint.
  • Installing or debugging third-party code or services you add.
  • Hosting, server or domain configuration beyond the guidance in this document.

To get the fastest answer

  • Tell us the template version (see the cover of this guide), your Node.js version (node -v) and your host.
  • Describe the steps that show the problem, and include any error message from the terminal or browser console.
  • Include a link to your site if it is online.

Support periods and what they cover are set by the Envato item support policy. If ClueCircuit helps your project, a rating on ThemeForest is much appreciated.

25.Licence

Your use of ClueCircuit is governed by the Envato Market licence you purchased, Regular or Extended. In short, each licence covers one end product (for example one venue website); the Extended licence is needed when end users are charged for that product. You may not redistribute or resell the template itself, alone or bundled, even if modified. Read the full terms at themeforest.net/licenses/standard.

The third-party software and fonts listed below keep their own open-source licences.

26.Sources & credits

ItemLicenceSource
Next.jsMITgithub.com/vercel/next.js
React and React DOMMITgithub.com/facebook/react
Newsreader (font)SIL Open Font License 1.1 — src/fonts/newsreader/OFL.txtGoogle Fonts
Figtree (font)SIL Open Font License 1.1 — src/fonts/figtree/OFL.txtGoogle Fonts
Nunito (font)SIL Open Font License 1.1 — src/fonts/nunito/OFL.txtGoogle Fonts
Anton (font)SIL Open Font License 1.1 — src/fonts/anton/OFL.txtGoogle Fonts
Oswald (font)SIL Open Font License 1.1 — src/fonts/oswald/OFL.txtGoogle Fonts
IBM Plex Sans (font)SIL Open Font License 1.1 — src/fonts/ibm-plex-sans/OFL.txtGoogle Fonts
IBM Plex Mono (font)SIL Open Font License 1.1 — src/fonts/ibm-plex-mono/OFL.txtGoogle Fonts
Hanken Grotesk (font)SIL Open Font License 1.1 — src/fonts/hanken-grotesk/OFL.txtGoogle Fonts
Saira Extra Condensed (font)SIL Open Font License 1.1 — src/fonts/saira-extra-condensed/OFL.txtGoogle Fonts
Caveat Brush (font)SIL Open Font License 1.1 — src/fonts/caveat-brush/OFL.txtGoogle Fonts

Development tools (not part of your website): TypeScript (Apache-2.0), ESLint (MIT), Vitest (MIT), Playwright (Apache-2.0), axe-core (MPL-2.0).

Icons are drawn for this template as inline SVG. Maps, floor plans and schedules are generated from data. Preview photography and illustrations are not included in the download (see Images).

27.Changelog

Version 1.0.0 — 21 November 2026

  • Initial release: showcase plus five venue demos (The Puzzle Club, Night Signal Rooms, After Hours, Fieldwork Games, Puzzle Dispatch), eight designed pages each, with a detail page for every room or game.
  • Static export with single-venue builds and sub-folder deployment.
  • Demo and connected enquiry modes, booking handoff, and printable, shareable plans.
  • Per-venue code splitting, self-hosted fonts and sized images for fast pages.