Getting Started

This guide walks you through creating your first headless funnel project, from installation to deployment.

Prerequisites

• Node.js 18+ — download here  if you don’t have it.
• An AppFunnel account with at least one project created. Sign in at appfunnel.net  and create a project if you haven’t already.

Setup

npm install -g appfunnel

appfunnel login

appfunnel init

cd my-funnel
appfunnel dev

Project Structure

After running appfunnel init, your project looks like this:

my-funnel/
├── appfunnel.config.ts    # Funnel configuration
├── tsconfig.json
├── src/
│   ├── funnel.tsx         # Layout wrapper (rendered around every page)
│   ├── app.css            # Global styles (Tailwind)
│   └── pages/
│       ├── index.tsx      # First page
│       ├── loading.tsx    # Loading page
│       └── result.tsx     # Result page
└── locales/
    └── en.json            # Translations

• appfunnel.config.ts — Defines which project and funnel this code belongs to, along with variables, products, and settings. See Configuration.
• src/funnel.tsx — A layout wrapper rendered around every page. This is where you add global UI (headers, progress bars, fonts) or your own React context providers.
• src/pages/*.tsx — Each file is a funnel page. The file name (without extension) becomes the page slug used in routing. Use lowercase with dashes (e.g. choose-goal.tsx, loading.tsx). Nested folders are not supported — all pages must be directly in src/pages/.
• locales/en.json — Translation strings in { "key": "value" } format. Use {{name}} for interpolation. Access via the useTranslation hook.

funnel.tsx

The funnel wrapper is a plain React component. The SDK handles FunnelProvider and page rendering automatically — you just control the layout:

import './app.css'
 
export default function Funnel({ children }: { children: React.ReactNode }) {
  return (
    <div className="min-h-screen">
      {children}
    </div>
  )
}

Add shared UI here — a progress bar, a back button, background styling, or any context providers your pages need. The children prop is the current page component.

locales/en.json

Translation files are flat JSON with {{variable}} interpolation:

{
  "welcome": "Welcome to the quiz",
  "greeting": "Hello, {{name}}!",
  "step_counter": "Step {{current}} of {{total}}"
}

const { t } = useTranslation()
t('greeting', { name: 'John' })  // "Hello, John!"

Your First Page

Every page exports a page definition and a default React component. Here is a minimal example:

import { definePage } from '@appfunnel-dev/sdk'
import { useNavigation, useResponse } from '@appfunnel-dev/sdk'
 
export const page = definePage({
	name: 'Welcome',
	routes: [{ to: 'loading' }],
})
 
export default function Welcome() {
	const { goToNextPage } = useNavigation()
	const [name, setName] = useResponse<string>('name')
 
	return (
		<div>
			<h1>What's your name?</h1>
			<input
				value={name ?? ''}
				onChange={(e) => setName(e.target.value)}
			/>
			<button onClick={goToNextPage}>Continue</button>
		</div>
	)
}

• definePage — Declares the page name and its outgoing routes. The to value matches a file name in src/pages/.
• useNavigation — Provides goToNextPage, goToPage, and other routing helpers.
• useResponse — Reads and writes a variable scoped to this page. The value is automatically persisted to the session.

Deploy

When you’re ready to go live, build and publish in two steps:

appfunnel build

appfunnel publish

Next Steps

• Configuration — Customize appfunnel.config.ts with products, locales, and build options.
• Hooks — Full reference for useVariable, useNavigation, useProducts, and more.
• Elements — Pre-built interactive components like SingleSelect, Dialog, and SpinnerWheel.
• Payments — Integrate Stripe or Paddle checkout into your funnel.