Next.js boilerplate with DataFast

One place a goal is born

src/lib/analytics/goals.ts declares every goal this repo sends. A goal not in GoalCatalogue does not compile. That is the point.

• Never call window.datafast() directly. Use trackGoal() from @/lib/analytics/datafast-client in the browser and trackGoalServer() from @/lib/analytics/datafast-server on the server.
• Never add data-fast-goal attributes. They skip the catalogue, the type check and the PII filter.
• A new goal means three edits in goals.ts: the name, its property type, and its line in GOAL_QUESTIONS. /add-goal does all three.
• Page views are not goals. The script records them, App Router navigations included. Never fire a page view by hand.

Naming

object_verb, past tense, snake_case, at most 64 characters. Checked by GOAL_NAME_PATTERN.

Write this	Not this	Why
checkout_started	startCheckout	A goal records something that happened
signup_completed	signup-complete	One casing, past tense
project_created	create_project	Object first, so the list groups by object
onboarding_step_completed	onboarding_2_done	The step is a property, not part of the name

• Never use a name in RESERVED_GOAL_NAMES: payment, subscription_started, trial_started, identify and the rest. DataFast sends those itself once a payment provider is connected. A custom payment goal pollutes revenue.
• Never encode a value in a name. plan_pro_bought and plan_team_bought are one goal with a plan property.

Properties

• Low-cardinality labels you will filter by: plan, source, step, method.
• At most 10 per goal, values at most 255 characters, all sent as strings. toGoalMetadata() enforces this and drops the rest.
• No personal data. DataFast's own docs pass email and name as goal parameters. Do not copy that. FORBIDDEN_PROPERTY_KEYS strips them; do not rename email to contact to get past it.
• No free text a user typed, no ids from another company's system, no secrets.
• identifyVisitor() takes your database user id. Never the email.

Which side fires it

• Browser (trackGoal): intent and interface. checkout_started, signup_started, a button a user clicked.
• Server (trackGoalServer): facts after a write. signup_completed, onboarding_step_completed, newsletter_subscribed. Needs DATAFAST_API_KEY.
• Never both for the same name. That doubles every count.
• Money is neither. Payments reach DataFast from the payment provider. See the revenue attribution rule.

DataFast attributes a payment to a channel by reading datafast_visitor_id from the checkout's metadata. No metadata, no attribution: the sale shows up as direct traffic and your best channel looks like your worst.

• Every checkout, subscription or one-off, is created with its params passed through withCheckoutAttribution() from @/lib/analytics/attribution. The payment batteries already do this through the checkout-attribution slot. A new checkout path you add by hand must do it too.
• Read the ids on the server, from the request cookies, inside the server action or route handler that creates the checkout. Never accept a visitor id from a request body: it is a claim, and it would let anyone attribute revenue to any channel.
• Never add revenue as a custom goal. No payment goal, no purchase_completed with an amount. DataFast reads payments from the connected provider and de-duplicates them. A goal copy double counts.
• withCheckoutAttribution() only adds keys. It never replaces userId or any other metadata the webhook relies on.
• Attribution respects consent. In "required" mode it adds nothing until the visitor agreed. Do not bypass that by reading the cookie yourself.
• The payment provider must also be connected in the DataFast dashboard. That is a one-time manual step, not code. If revenue shows as zero, check that first.

Loading

• The script is rendered once, by AnalyticsProvider in src/lib/analytics/provider.tsx, with next/script and strategy="afterInteractive". Never beforeInteractive, never a raw <script> in <head>, never a second copy in a page.
• The provider renders the script beside the app, not around it. Nothing in the tree may wait for analytics. No await, no loading state, no Suspense boundary that depends on window.datafast.
• A missing NEXT_PUBLIC_DATAFAST_WEBSITE_ID means "render nothing". It must never throw, and next build must pass with no env vars set.
• Calls before the script loads are queued by installQueue(). Do not add a second queue snippet.

Proxy

• src is /js/script.js and data-api-url is /api/events. Both are route handlers in this repo that forward to datafa.st. The browser never talks to datafa.st directly. Do not "simplify" src back to https://datafa.st/js/script.js: blocklists match that hostname.
• src/app/api/events/route.ts forwards the visitor's IP, user agent, origin and referer. Remove those and every visitor is geolocated to your server.
• Both routes answer inert on upstream failure: an empty script, a 204. A failing analytics call must never put a red error in a visitor's console.
• If a route path collides with one of yours, rename the folder and update the matching constant in datafast-client.ts. Nothing else references it.

Consent

• src/lib/analytics/consent.ts owns the policy. CONSENT_MODE is the only switch.
• In "required" mode the script is not rendered, goals are not queued and checkouts carry no visitor id until grantAnalyticsConsent() runs. Every new code path that sends data to DataFast checks hasAnalyticsConsent().
• Proxying changes the hostname, not the law. It is never a way around consent.