Listings and datasets
A listing is a row in D1. On your machine that is the local database pnpm dev seeds; behind
your site it is the real one, which a production build reads with
three credentials. Rows arrive three ways — the importer, a dataset,
an approved submission — and the slug is the URL: acme is /<routes.listingBase>/acme/. The
description is the body of the detail page.
The listing schema
Section titled “The listing schema”| Field | Required | Default | Rule |
|---|---|---|---|
name |
yes | — | 1 to 80 characters |
url |
yes | — | an absolute URL |
tagline |
yes | — | 1 to 160 characters |
category |
yes | — | a categories[].slug |
approvedAt |
yes | — | a date, 2026-01-05; the newest sort |
logo |
no | null |
https://…, or /logos/<file> inside a dataset; the seed stores it in the bucket |
screenshots |
no | [] |
URLs or /-rooted paths |
tags |
no | [] |
tags[].slug; unknown ones dropped with a warning |
pricingType |
no | free |
a pricingTypes[].slug |
tier |
no | free |
a tiers[].id |
featuredUntil |
no | null |
a date; featured until then when the tier’s kind is featured |
popularity |
no | 0 |
a whole number; the popular sort |
createdAt |
no | — | a date |
extra |
no | {} |
custom values — Custom fields |
The same fields are the columns a spreadsheet needs and the frontmatter of a dataset file.
Import a spreadsheet
Section titled “Import a spreadsheet”-
Dry-run the file.
Terminal pnpm listings:import my-data.csv --dry-runCSV with a header row, or a JSON array; one verdict per row, nothing written:
listings:import — my-data.csv (csv, 3 rows) → D1 (dry run)ok row 1 acme-writer upsert Acme Writerok row 2 jasper upsert Jasper (1 warning)error row 3 (Zed): unknown category "marketing" (slug "zed"); categories in site.config.ts: writing, codingwarn row 2 (Jasper): unknown tag(s) "foo" filtered (slug "jasper"; not in site.config.ts tags)warn ignored column(s) not in the listing schema: Notes (use --map or an "extra.<key>" header)dry run: 2 ok, 1 error; nothing writtenColumn Rule headers aliases, lower-cased: Title→name,Website→url,Summary→tagline,Body→description(the Markdown body),Keywords→tags,Pricing→pricingType,Plan→tier,Date added→approvedAt--map name=Product,url=Websitea header the aliases miss; wins over them extra.founded, or a header equal to alisting.customFields[].keylands in extra; anextracolumn of JSON is merged tooname,url,tagline,categoryrequired: row 3 (Zed): missing required column "url"slugoptional; else the slugified name, a duplicate gets-2tags, datessplit on commas, semicolons, pipes or line breaks; any date format becomes YYYY-MM-DD,approvedAtdefaulting to todaypricingType,tier,logothe schema’s rules, but a bad value is an error -
Run it.
Terminal pnpm listings:import my-data.csv --localAll-or-nothing: one bad row and it prints
1 row cannot be imported; nothing was written:with the rows. When every row passes:upserted 3 listing(s) into the local database--remotewrites the real database instead. A row is upserted on its slug, so re-importing a corrected file edits the listings that are already there. -
Check and build.
Terminal pnpm check:config && pnpm buildBoth counts in Verify should have grown.
Custom fields
Section titled “Custom fields”A key declared in listing.customFields renders in the facts card, on the card with
showOnCard: true, and on the submit form, where required applies.

listing: { customFields: [ { key: 'founded', label: 'Founded', type: 'text', showOnCard: true }, { key: 'platforms', label: 'Platforms', type: 'select', options: ['Web', 'macOS', 'iOS'] }, { key: 'docsUrl', label: 'Documentation', type: 'url' }, ],},A key matches ^[a-z][a-zA-Z0-9]*$, may not shadow a
built-in listing column, and reads the listing’s extra.
type is text, url, select or textarea; a select needs options.
Datasets
Section titled “Datasets”seed/datasets/ holds ai-tools (the demo, real products), indie-tools and local-businesses
(invented, example.com URLs), each with listings/, blog/, logos/, categories.json,
tags.json, meta.json. A dataset is a seed, never a source: nothing builds from these files.
pnpm content:use local-businesses --yes # seed the local database with one, copy its postspnpm content:reset --yes # delete the demo data from the local databasepnpm listings:export --local # a database back out, in the same formatAdd --remote to act on the real database. The first pnpm dev runs the first command for
ai-tools on an empty database, logos included.
Verify
Section titled “Verify”| Where | You should see | |
|---|---|---|
| The config | pnpm check:config |
site.config.ts OK — <name> (<url>); …, then listings: N (the local database); logos optimised from R2 (+1 webp each) |
| The build | pnpm build |
[zerodirs-d1] D1 (local): N approved listings (featured N, 30-day clicks for N, N wrangler calls) |
| A listing | pnpm preview, then /<routes.listingBase>/<slug>/ |
name, tagline, the logo or the letter tile, the body |
| The database | pnpm exec wrangler d1 execute DB --local --command "SELECT count(*) FROM listings WHERE status='approved'" |
the same N |
Worth knowing
Section titled “Worth knowing”- Only strings, numbers and booleans render from
extra;customFieldValue()drops anything else without a warning. Keep a structured value under its ownextrakey. content:usenever editssite.config.ts: fromseed/.out/<dataset>-config.txt, paste thecategoriesandtagsblocks yourself, and copy thesite.kind,routes.listingBase,routes.listingNounandseo.jsonLd.listingvalues it comments out (local-businessessuggestsroutes.listingBase: 'places'). Then runpnpm check:config.content:reset --yesdeletes the seeded rows, their logos in the bucket and every post but the starter’s draft fixture, and leaves the database empty. Imports and approved submissions are never touched, byresetor byuse. Without--yeseither command refuses and says what it would do.- The
ai-toolsentries and posts describe real products; they are not yours to republish. - Approving a submission in
/admin/adds a row the same way, and the next build renders it without a commit.
When the build fails
Section titled “When the build fails”| Message | Result |
|---|---|
listings › my-tool: unknown category "marketing" (slug "my-tool"); categories in site.config.ts: writing, chatbots, image-generation, coding |
fails |
listings loader: the local database has no listings table |
fails — run pnpm dev once, or pnpm db:migrate:local && pnpm db:seed:local |
listings › my-tool: unknown tag(s) "foo" filtered (slug "my-tool"; not in site.config.ts tags) |
warns; the tag is dropped from that listing |
Configuration
Section titled “Configuration”routes.listingBase (routes); listing.perPage, defaultSort, relatedCount, maxTags, screenshotMax, outboundRel and customFields (listing); and the vocabularies a listing has to match — categories, tags, pricingTypes, tiers.
Directory
src/Directory
content/schema.ts—listingSchema, the one shape a row is normalised into
content.config.ts— wires the collection tolistingsLoader()Directory
loaders/index.ts— which database the build readsd1-local.ts— the local database, through wranglernormalize.ts— the category check, the tag filter,isFeatured
Directory
scripts/import.ts—pnpm listings:importcontent.ts—pnpm content:reset,content:useseed.ts—pnpm db:seed:local,db:seed:remote
Directory
seed/Directory
datasets/— the sample datasets- …