Docs · Developers
Developer guide
How FirstPass is put together and how to change it. The source is on GitHub.
Overview
FirstPass is a Next.js app with no accounts and no database for answers. The visitor’s answers live in their browser, the rules are plain TypeScript, and a handful of small API routes do the few things a browser can’t.
| Piece | Choice |
|---|---|
| Framework | Next.js 16 (App Router, Turbopack) and React 19 |
| Language and styling | TypeScript and Tailwind CSS 4, with design tokens in app/globals.css |
| State | Browser storage only, shared between pages with useSyncExternalStore |
| Rules | Pure functions over the answers: no network, so they run instantly and are easy to test |
| Free services | Google Gemini (store page text), Pollinations (background pictures), Resend (feedback email), Vercel Blob (beta sign-ups) |
| Hosting | Vercel, deployed from the main branch |
Run it locally
git clone https://github.com/Matanza00/PlayStore.git cd PlayStore npm install npm run dev
Open http://localhost:3000. Everything works with no settings, because every outside service is optional.
npx tsc --noEmit npx eslint app lib components npm run build
Settings
Copy .env.example to .env.local to use them locally. On Vercel, add them under Project Settings, Environment Variables, then redeploy: a change only applies to new deployments.
| Name | Needed? | What it does |
|---|---|---|
GEMINI_API_KEY | Optional | Free key from Google AI Studio. Without it, the studio writes a simple template from the visitor's own words. |
GEMINI_MODEL | Optional | Any Gemini model with a free tier. Defaults to gemini-3.5-flash-lite. |
RESEND_API_KEY | For feedback | Sends the feedback email. Without it, the form says nothing was sent and offers a mailto link. |
FEEDBACK_TO | Optional | Where feedback is delivered. Defaults to support@nxcsol.com. |
FEEDBACK_FROM | Optional | The sender, on a domain verified in Resend. Defaults to FirstPass <feedback@nxcsol.com>. |
BLOB_READ_WRITE_TOKEN | For beta sign-ups | Added automatically when a Vercel Blob store is connected to the project. Without it, the beta page says nothing was saved and the front page shows no count. |
Keep keys out of the repo. .env.local is ignored by git, and the keys are only ever read on the server.
Project layout
| Path | What lives there |
|---|---|
lib/questions.ts | The whole questionnaire as data: steps, questions, options and which ones show for which answers. |
lib/rules.ts | evaluate(): turns answers, the build report and link checks into findings. About 40 rules. |
lib/scan.ts | The build check prompt, the report type, and a forgiving parser for what people paste back. |
lib/listing.ts | Length limits and wording checks for the store title and descriptions. |
lib/client-info.ts | Reads IP, device and browser from request headers, for feedback emails. |
lib/beta.ts | Beta tester sign-ups in a private Vercel Blob store: one small file per device, a cached count and the newest names. |
lib/feedback-email.ts | Builds the feedback email, as HTML and plain text, escaping everything typed by visitors. |
components/CheckFlow.tsx | The wizard and the results page. |
components/Studio.tsx | The store page studio: words, feature graphic, screenshots and icon, drawn on canvases. |
components/shared.tsx | The browser storage hook and small helpers. |
app/api/*/route.ts | The five server routes. See the API reference below. |
docs/ | The Google Play policy research the rules are based on. |
Data and storage
Everything the visitor enters is saved in localStorage under the key firstpass.v1. The check and the studio share it, so what someone writes in one shows in the other.
type Saved = {
answers: Record<string, string | string[] | undefined>; // keyed by question id
scanRaw: string; // the pasted build report
done: string[]; // ids of findings marked "fixed"
};If the browser refuses storage, such as in a private window, the app still works for that visit. Nothing in storage is sent anywhere unless an endpoint below says so.
The build report
The build check hands the visitor a prompt, and they paste back the JSON their AI tool answers with. parseScan() extracts the first {…} block, so extra chatter around it is fine. Every field is optional, and null means “couldn’t tell”.
| Field | Type | Used for |
|---|---|---|
framework, frameworkVersion, expoSdk | string, number | Stack-specific fix prompts. |
packageName, versionCode | string, number | Context in prompts. |
targetSdk, minSdk | number | The target API rule (Google currently requires 36). |
permissions | string[] | Permissions packages added that the visitor didn't mention. |
sdks, paymentSdks, adSdks | string[] | Payments and ads cross-checks. |
billingLibraryVersion | string | The Play Billing version rule (8 or newer). |
hasNativeLibraries, supports16KbPageSize | boolean | The 16 KB memory page rule. |
debuggable, usesCleartextTraffic, isMostlyWebView | boolean | Upload and quality checks. |
hasAccountDeletion, hasPrivacyPolicyLink, notes | boolean, string | Cross-checks against the answers. |
Add a rule
A rule is a call to add() inside evaluate() in lib/rules.ts. Every rule runs every time, so wrap it in the condition that makes it apply.
type Finding = {
id: string; // stable, unique: used to remember "I've fixed this"
severity: "blocker" | "warn" | "tip";
area: "Account" | "Privacy" | "Permissions" | "Content" | "Money" | "Build" | "Store page" | "Play Console";
policy: string; // the name Google uses for this rule in its emails
title: string; // plain words, no jargon
what: string; // why it matters, in a sentence or two
steps: string[]; // what to do, in order
prompt?: string; // for code fixes: wrap with prompt(a, "...")
source: { label: string; url: string }; // Google's own page
deadline?: string; // shows a "From <date>" tag for announced rules
};if (is(a, "hasLogin", "yes") && is(a, "canDelete", "no")) {
add({
id: "delete-in-app",
severity: "blocker",
area: "Privacy",
policy: "Account deletion requirement",
title: "People must be able to delete their account in the app",
what: "If someone can create an account, Google requires a way to delete it from inside the app.",
steps: ["Add a Delete my account option to settings.", "Ask for confirmation, then delete the data."],
prompt: prompt(a, "Add a Delete my account option to the settings screen…"),
source: src.deletion,
});
}Add a question
Questions are data in lib/questions.ts, so changing the wording or adding one needs no form code.
{
id: "hasLogin", // the key in answers
label: "Do people sign in or create an account?",
help: "Optional line of help under the question.",
type: "single", // text | longtext | url | single | multi
options: [{ value: "yes", label: "Yes" }, { value: "no", label: "No" }],
optional: false, // optional questions can be skipped
showIf: (a) => is(a, "stack", "flutter"), // only show when this is true
}Then read the answer in a rule with the helpers is(a, id, value), has(a, id, value) for multiple choice, and text(a, id) for free text.
API reference
Five routes, all POST with a JSON body (/api/beta also accepts DELETE). They exist for the few things a browser can’t do alone, and every one is optional to the main check.
POST /api/check-url
Opens a privacy policy or account deletion link the way a reviewer would and reports what is wrong.
// request
{ "url": "https://example.com/privacy", "kind": "privacy" | "deletion", "appName": "Tiffin Tracker" }
// response 200
{ "url": "https://example.com/privacy", "ok": false, "problems": ["The link uses http. It needs to start with https."] }Returns 400 for a body that isn’t JSON. Only public web pages are fetched.
POST /api/write-listing
Drafts store page text with Gemini.
// request
{ "appName": "Tiffin Tracker", "oneLiner": "Helps home cooks take lunch orders", "category": "general", "features": "Take orders\nTrack deliveries" }
// response 200
{ "title": "…", "shortDesc": "…", "fullDesc": "…" }| Status | Meaning |
|---|---|
400 | The app name or one-sentence description is missing. |
501 | No key is set ({ "error": "no-key" }). The studio falls back to a template. |
502 | Gemini was busy or didn't answer. |
POST /api/background
Fetches a free AI background picture for the feature graphic, passed through as image bytes.
// request
{ "description": "warm kitchen counter with lunch boxes" }
// response 200: the image (content-type image/*), 1024 × 500| Status | Meaning |
|---|---|
400 | The description is under three characters. |
429 | The free service allows one picture every 45 seconds. |
502 / 504 | The picture service didn't answer or took too long. |
POST /api/feedback
Emails feedback to the team through Resend, with the sender’s IP address, device and browser read from the request headers.
// request
{ "message": "Required, 5 to 2,000 characters", "rating": 1-5 (optional), "email": "optional", "from": "results" (optional) }
// response 200
{ "ok": true }| Status | Meaning |
|---|---|
400 | The message is too short or too long, or the email address doesn't look right. |
413 | The request body is over 10 KB. |
429 | More than five messages an hour from one visitor. |
501 | No Resend key is set ({ "error": "not-configured" }). |
502 | Resend refused or didn’t answer ({ "fallback": true }). |
POST /api/beta and DELETE /api/beta
Counts someone as a beta tester, anonymously or with a name the site may show, and removes them again. Each device is one small file in a private Vercel Blob store, named by a one-way code made from the IP address and browser, so a person counts once and no address is stored.
// POST request
{ "mode": "anonymous" | "named", "name": "Faraz" (only when mode is "named") }
// POST response 200
{ "ok": true, "named": true }
// DELETE: no body. Removes this device from the list and the count.
// DELETE response 200
{ "ok": true }| Status | Meaning |
|---|---|
400 | A named sign-up needs 2 to 30 letters (spaces, dots, hyphens and apostrophes are allowed, no links or numbers). |
413 | The request body is over 2 KB. |
429 | More than five requests an hour from one visitor. |
501 | No Blob store is connected ({ "error": "not-configured" }). |
502 | The store didn't answer. |
Security notes
- Link checks can’t reach private networks.
/api/check-urlrefuses localhost, internal and private addresses, checks every redirect hop against the same rule, follows at most five redirects, and gives up after 12 seconds. - Feedback is escaped. Everything a visitor types is HTML-escaped before it goes into the email, and the address used for replies is validated.
- Abuse is limited. Five feedback messages an hour per visitor, and a small body size. The counter lives in each server instance’s memory, so it is a best-effort limit, not a guarantee.
- Keys stay on the server. No secret is exposed to the browser, and no answer is stored server-side.
- Disclosure. The feedback page tells visitors their IP address, device and browser are sent with the message.
Deploy
The project is linked to its GitHub repository on Vercel, so every push to main builds and deploys. It runs at fp.nxcsol.com. To run your own copy for noncommercial use, import the repository into Vercel, add the settings above if you want them, and deploy. Offering a copy to others as a service needs a commercial licence.
The rules reflect Google Play policy as read on 14 November 2026. The research behind them is in the docs/ folder of the repository, and every finding links to Google’s own page so it can be re-checked.
Contributing
The FirstPass code is public and open to contributions from anyone, under a noncommercial licence (see the licence page). Fork the repository, make one focused change, run the three checks above, and open a pull request. Changes to rules must link to Google’s own page and say when it was read.
- CONTRIBUTING.md has the full guide.
- The contribute page explains it for people who don’t write code.
- Open an issue for a bug, an idea, or a rule that is out of date.
Something missing or wrong?
These docs follow the app as it works today. If a step doesn’t match what you see, tell us.
Send feedback