Skip to content
Early bird + Black Friday · 73% off

Get ZeroDirs for $179 $49

Claim $49 deal

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.

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.

  1. Dry-run the file.

    Terminal
    pnpm listings:import my-data.csv --dry-run

    CSV 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 Writer
    ok row 2 jasper upsert Jasper (1 warning)
    error row 3 (Zed): unknown category "marketing" (slug "zed"); categories in site.config.ts: writing, coding
    warn 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 written
    Column 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=Website a header the aliases miss; wins over them
    extra.founded, or a header equal to a listing.customFields[].key lands in extra; an extra column of JSON is merged too
    name, url, tagline, category required: row 3 (Zed): missing required column "url"
    slug optional; else the slugified name, a duplicate gets -2
    tags, dates split on commas, semicolons, pipes or line breaks; any date format becomes YYYY-MM-DD, approvedAt defaulting to today
    pricingType, tier, logo the schema’s rules, but a bad value is an error
  2. Run it.

    Terminal
    pnpm listings:import my-data.csv --local

    All-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

    --remote writes the real database instead. A row is upserted on its slug, so re-importing a corrected file edits the listings that are already there.

  3. Check and build.

    Terminal
    pnpm check:config && pnpm build

    Both counts in Verify should have grown.

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.

A listing page on the demo, with the custom fields in the facts card beside the description

site.config.ts
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.

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.

Terminal
pnpm content:use local-businesses --yes # seed the local database with one, copy its posts
pnpm content:reset --yes # delete the demo data from the local database
pnpm listings:export --local # a database back out, in the same format

Add --remote to act on the real database. The first pnpm dev runs the first command for ai-tools on an empty database, logos included.

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
  • Only strings, numbers and booleans render from extra; customFieldValue() drops anything else without a warning. Keep a structured value under its own extra key.
  • content:use never edits site.config.ts: from seed/.out/<dataset>-config.txt, paste the categories and tags blocks yourself, and copy the site.kind, routes.listingBase, routes.listingNoun and seo.jsonLd.listing values it comments out (local-businesses suggests routes.listingBase: 'places'). Then run pnpm check:config.
  • content:reset --yes deletes 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, by reset or by use. Without --yes either command refuses and says what it would do.
  • The ai-tools entries 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.
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

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.

  • Directorysrc/
    • Directorycontent/
      • schema.ts — listingSchema, the one shape a row is normalised into
    • content.config.ts — wires the collection to listingsLoader()
    • Directoryloaders/
      • index.ts — which database the build reads
      • d1-local.ts — the local database, through wrangler
      • normalize.ts — the category check, the tag filter, isFeatured
  • Directoryscripts/
    • import.ts — pnpm listings:import
    • content.ts — pnpm content:reset, content:use
    • seed.ts — pnpm db:seed:local, db:seed:remote
  • Directoryseed/
    • Directorydatasets/ — the sample datasets
      • …