flux-kontext-template is a Next.js shell for selling AI image generation

The pitch is the boring half of an AI product

The README frames the repository as a base for building an AI image generation site quickly rather than as a technical demo, and the pieces it lists are the ones every such product ends up needing. Out of the box you get Next.js 16 with React 19 and TypeScript, Google login, a credits system, entry points for image generation and editing, a provider adaptation layer for fal, KIE and WaveSpeed, payment integration with Stripe and Creem, a Supabase database, Cloudflare Turnstile for abuse prevention, Cloudflare R2 for file storage, a multilingual page skeleton, and basic SEO, analytics and deployment scaffolding. The README is also explicit about who this is not for, listing people who do not want to touch environment variables or register third party services, and people who only want a static landing page. That framing matters, because a template like this is mostly a set of decisions someone else made, and the ones it makes for you are the ones you will inherit.

Two payment providers are wired, PayPal is only reserved

The README devotes a section to correcting a common misreading of the repository, and the correction is specific. The number of genuinely integrated payment providers is two, Stripe and Creem. A generic webhook route in the repository mentions paypal, but that branch is still reserved rather than a complete production integration, so the correct count is two supported payment providers, not three. The image the README uses is that there are two tills actually open for business, Stripe and Creem, while PayPal is more like a socket left on the counter that is not yet powered. That level of care about a claim is a good sign, and it also tells you that a PayPal integration is work you would be starting, not finishing. The point of the section is that when you read the file tree and see a PayPal route, you should not plan around it.

The database layer looks like Prisma and is not Prisma

The second clarification in the README concerns the data layer, and it is the kind of trap that costs a day. The main database plan is Supabase PostgreSQL, with Supabase Auth and NextAuth handling authentication, Supabase PostgreSQL holding the business data, and the code access layer being a hand written Prisma style adapter. The file src/lib/database.ts exports an object called prisma, but it is not the Prisma ORM, it is a Supabase adapter that happens to look like Prisma. The README insists you remember this, because otherwise you will think a dependency is missing or that a schema.prisma file is absent, and the answer to both is no, because the current main path of the repository is Supabase. The core tables are defined in scripts/setup-database.sql and are users, orders, credit_transactions, subscriptions and payment_configs, which map to a membership table, an order table, a credit ledger, a subscription relation and a checkout configuration table.

The request path is nine steps and one facade

The README walks through the user path in a way that doubles as an architecture description. A user opens the home page or /generate, logs in, types a prompt or uploads a reference image, and the front end posts to /api/flux-kontext. The server then checks whether the user is logged in, whether they have credits, whether Turnstile is required and whether the parameters are valid. It hands the request to a unified provider facade, the current provider calls fal, KIE or WaveSpeed, and on the way back the image can optionally be saved to R2 before the front end shows the result and offers further editing or download. The facade is the piece to look at when you want to change behaviour, and the README points at src/lib/flux-kontext.ts, src/lib/image-generation/types.ts and src/lib/image-generation/providers/ as the files for the route where you build your own provider platform. The other edit targets it names are src/app/ and src/components/ for pages and visuals, src/components/FluxKontextGenerator.tsx and src/components/flux-kontext/ for the generator UI, src/app/api/flux-kontext/route.ts for the server entry point, and src/lib/user-tiers.ts plus src/api/user/* for user and credit logic.

Getting it running takes a clone, a copy and a key

The short path to a running site is spelled out. You need Node.js 20 or newer, npm and Git on your machine, then a clone and an install.

git clone https://github.com/CharlieLZ/flux-kontext-template.git
cd flux-kontext-template
npm ci

The environment template is copied rather than created by hand.

cp env.example .env.local

The minimum set of variables for a site that can actually log a user in and generate an image is listed explicitly.

FAL_KEY=""
NEXT_PUBLIC_SUPABASE_URL=""
NEXT_PUBLIC_SUPABASE_ANON_KEY=""
SUPABASE_SERVICE_ROLE_KEY=""
DATABASE_URL=""
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET=""
GOOGLE_ID=""
GOOGLE_SECRET=""

After that, the dev server runs on port 3000, and a lint pass plus a production build tells you whether the skeleton holds together.

The provider is a single environment variable, and fal is the paved road

Switching the image backend is one setting.

IMAGE_GENERATION_PROVIDER="fal"

The allowed values are fal, kie and wavespeed, and the README recommends starting with fal because the default main path of the repository has already been shaped around it, while KIE and WaveSpeed are described as better suited to a later stage when you need webhooks and task queues. That is an honest piece of advice and it also tells you where the sharp edges are. Setting a provider to kie requires a KIE_API_KEY and, for webhooks, a KIE_WEBHOOK_SIGNING_SECRET. Setting wavespeed requires a WAVESPEED_API_KEY and, again for webhooks, a WAVESPEED_WEBHOOK_SECRET. The README also describes an Atlas Cloud option that calls the Black Forest Labs FLUX family directly, including FLUX.2 Pro, FLUX.2 Flex, FLUX Dev and FLUX Schnell, as a task style interface, with support for two actions beyond the six the other providers offer, including text-to-image-schnell.

Optional services degrade the product rather than blocking it

The README is clear about which keys are load bearing and which are not, and the degradation story matters for a launch plan. The R2 keys store images in Cloudflare R2, and without them the pages still open while some post generation storage paths degrade or report a prompt. The Stripe keys handle charging, and without them you cannot take money, but you can still build and test the product. The Turnstile keys, NEXT_PUBLIC_ENABLE_TURNSTILE, NEXT_PUBLIC_TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY, are the anti abuse layer. The database setup step is the one that catches people out, because the README warns that if you skip running setup-database.sql the page opens and login looks like it worked, while the users, orders and credit transaction tables were never created. The scripts/check-config.js command, wired as npm run check, checks for missing configuration, and npm run check:supabase checks Supabase connectivity, which is why the recommended self check order puts npm run check before lint and build.

Where the template stops being a template

Three limits are worth naming before you build on it. The first is the provider abstraction depth. The facade is a switch, not a general plugin system, so a provider with genuinely different semantics, a task queue with polling rather than a synchronous call, needs work rather than configuration. The second is that the project has one tagged release, v0.1.0 from 2026-03-08, while the last push was on 2026-10-19, so the repository moves faster than its versions and there is no migration path documented between tags. The third is the payment surface itself. The repository includes a PAYMENT_SECURITY_GUIDE.md, a SECURITY.md and a scripts/setup-database.sql, and the credits model with credit_transactions, orders and subscriptions is a real accounting system rather than a demo stub, but it is also untested against your own pricing, refund and dispute handling. The package.json also names the project nextjs-shadcn at version 0.1.0 and marks it private, which suggests the template was derived from a broader starter rather than purpose built for this product.

Editorial conclusion

flux-kontext-template suits a developer who has decided to sell AI generated images and wants the login, credit accounting, payment and storage layers in place before writing product code, and it suits anyone who plans to move between fal, KIE and WaveSpeed later. It is the wrong choice for a static landing page, and it is the wrong choice for someone who wants a provider-neutral abstraction, because the default path has been shaped around fal and the other providers are described as more suited to webhook and queue based work. Before deploying, run the setup-database.sql script, set the provider explicitly through IMAGE_GENERATION_PROVIDER, and read PAYMENT_SECURITY_GUIDE.md, since the template ships payment and webhook code that assumes you will review it. The last push was on 2026-10-19 and the only tagged release is v0.1.0 from 2026-03-08.

Frequently asked questions

Official sources

1. CharlieLZ/flux-kontext-template on GitHub
2. Issues
3. License: MIT
4. README
5. Releases