How to build a job directory and search page

Combine context, filters, numbered or cursor pagination, job cards, and canonical URLs.

A listing page should be driven by URL state so search engines and users can share the same result set.

Parse public URL state

Use the SDK’s filter vocabulary instead of accepting arbitrary values. Invalid public query parameters are dropped rather than throwing.

1// src/lib/load-jobs.ts
2import { parseListingFilters } from '@cavuno/board/filters';
3
4import { board } from './cavuno';
5
6export async function loadJobs(search: Record<string, unknown>) {
7  const filters = parseListingFilters(search);
8  const common = {
9    remoteOption: filters.remoteOption ? [filters.remoteOption] : undefined,
10    employmentType: filters.employmentType
11      ? [filters.employmentType]
12      : undefined,
13    seniority: filters.seniority,
14  };
15
16  if (filters.q) {
17    return board.jobs.search({
18      query: filters.q,
19      sort: filters.sort,
20      filters: common,
21      limit: 20,
22    });
23  }
24
25  return board.jobs.list({
26    ...common,
27    sort: filters.sort,
28    limit: 20,
29  });
30}

Browse uses GET board.jobs.list; free-text search uses POST board.jobs.search. Both return job cards with data, hasMore, and nextCursor. Catalog responses can also include count, limit, offset, and gatedCount.

To filter by the board's own job or company custom fields, such as an opportunity type or an employer type, follow Custom field filters and badges.

Format cards in the board language

Load board.context() once for the board language. Pass that language into every label-producing helper.

1import {
2  formatPublishedRelativeDate,
3  formatSalaryRange,
4} from '@cavuno/board/format';
5
6const context = await board.context();
7const page = await loadJobs(searchParams);
8
9const cards = page.data.map((job) => ({
10  ...job,
11  location: job.locationLabel,
12  published: formatPublishedRelativeDate(
13    context.language,
14    job.publishedAt,
15  ),
16  salary: formatSalaryRange(
17    context.language,
18    job.salaryMin,
19    job.salaryMax,
20    job.salaryTimeframe,
21    job.salaryCurrency,
22  ), // { text, timeframe, bound } | null — map enum + bound chrome app-side
23}));

Filter and badge by custom fields

Job custom fields can drive both listing filters and card badges. The definitions come from board.context().customFields.job: use each option's label as the control text and keep the option key in the URL (/jobs?work_type=contract), because labels change when the operator renames an option and keys do not. Send the selected keys as filters.customFields on board.jobs.search, and drop any URL value that is not a current option so it never reaches the API.

1const context = await board.context();
2const workType = context.customFields.job.find(
3  (field) => field.key === 'work_type',
4);
5const selected = searchParams
6  .getAll('work_type')
7  .filter((key) => workType?.options?.some((option) => option.key === key));
8
9const results = await board.jobs.search({
10  query: filters.q,
11  filters: {
12    customFields:
13      selected.length > 0 ? [{ key: 'work_type', values: selected }] : undefined,
14  },
15  limit: 20,
16});

Every job card carries customFieldValues for the job and company.customFieldValues for its company, so a badge needs no extra request per job. Only single-select, multi-select, yes/no and number values appear on cards; text fields stay on the full job and company, and private company fields never appear. Select values are option keys, so resolve them to labels before rendering. For job values, resolveCustomFieldDisplay does this against the job definitions:

1import { resolveCustomFieldDisplay } from '@cavuno/board/format';
2
3const badges = resolveCustomFieldDisplay(
4  context.language,
5  context.customFields.job.filter((field) => field.key === 'work_type'),
6  card.customFieldValues,
7);
8
9// Company values resolve against the public company definitions.
10const companyFields = await board.profileFields.retrieve('company');
11const tier = companyFields.definitions.find((f) => f.key === 'member_tier');
12const tierKey = card.company?.customFieldValues.member_tier;
13const tierBadge = tier?.options?.find((o) => o.key === tierKey)?.label ?? null;

Load both sets of definitions once per page, not once per card. Drop a value whose key or option has no current definition rather than printing the raw key.

Build the page head from the same result

Do not calculate metadata from different filters or a separate result set. The visible heading, result count, canonical path, and structured data should describe the same page.

1import { listingHead, listingJsonLd } from '@cavuno/board/seo';
2
3const origin = 'https://jobs.example.com';
4const path = pageNumber > 1 ? `/jobs?page=${pageNumber}` : '/jobs';
5const heading = 'Remote jobs';
6const countLabel = new Intl.NumberFormat(context.language).format(page.count);
7// Application owns title/description composition (counters, order, separators).
8const title = messages.listingTitle({
9  count: page.count,
10  countLabel,
11  heading,
12  boardName: context.name,
13});
14const description = messages.listingDescription({
15  count: page.count,
16  countLabel,
17  heading,
18  boardName: context.name,
19});
20
21const head = listingHead({
22  title,
23  origin,
24  path,
25  description,
26});
27
28const jsonLd = listingJsonLd({
29  origin,
30  breadcrumbs: [
31    { name: 'Home', path: '/' },
32    { name: heading },
33  ],
34  jobs: page.data,
35});

Map head.meta and head.links into the framework’s metadata API. Serialize each JSON-LD object safely into an application/ld+json script.

Most public directories should expose stable page URLs:

1const pageNumber = Math.max(1, Number(searchParams.page ?? '1'));
2const limit = 20;
3
4const page = await board.jobs.list({
5  ...filters,
6  limit,
7  offset: (pageNumber - 1) * limit,
8});

Preserve every active filter when generating ?page=2. Reset the page to 1 when the visitor changes a filter. Use the response’s hasMore, count, and gatedCount when present; do not fabricate a total.

Give each numbered page its own self-referencing canonical: /jobs for page 1 and /jobs?page=2 for page 2. Do not canonicalize the whole sequence to page 1. Render previous and next navigation as real <a href> links so crawlers and keyboard users can follow the sequence; a button-only “Load more” control is not a crawl path. See Google’s pagination guidance.

Treat arbitrary search, sort, and filter combinations as discovery states. They should normally use noindex,follow, while the unfiltered directory and each numbered page remain indexable. Index a filtered route only when you have deliberately created a stable landing page with a canonical path, unique useful content, internal links, and enough matching jobs.

Add a search distance to city pages

A city page such as /jobs/locations/houston-tx-united-states reads better when it also lists jobs a short commute away: "Showing 1–20 jobs within 25 mi ⌄ of Houston". The jobs API has no default distance, so your page decides it and passes radius in kilometres.

1import {
2  defaultSearchRadius,
3  distanceUnitForCountry,
4  formatDistance,
5  searchRadiusOptions,
6} from '@cavuno/board/format';
7
8const place = await board.taxonomy.places.resolve(placeSlug);
9const geo = place.geo;
10const canWiden =
11  (geo?.placeType === 'city' || geo?.placeType === 'locality') &&
12  geo.lat !== null &&
13  geo.lng !== null;
14
15const unit = distanceUnitForCountry(geo?.countryCode);
16const options = searchRadiusOptions(unit); // 5, 10, 25, 50, 100 in mi or km
17const fallback = defaultSearchRadius(unit); // 25 mi or 50 km
18
19// ?within=0 is exact location only; any other value must be a preset.
20const within = searchParams.within;
21const selected =
22  within === '0'
23    ? null
24    : (options.find((option) => String(option.value) === within) ?? fallback);
25
26const page = await board.jobs.list({
27  location: place.sourceSlug,
28  radius: canWiden && selected ? selected.km : undefined,
29  limit: 20,
30});
31
32const distanceLabel = selected
33  ? formatDistance(selected.value, selected.unit, board.language)
34  : null; // "25 mi"

Follow the same rules as hosted boards so search engines see one page per place:

Show the menu only when canWiden is true. Region and country pages, and places without coordinates, list jobs in the place and ignore within.
Offer "Exact location only" (within=0) and the five presets. When the visitor picks the default, drop within so the plain URL stays the default view. Treat an unknown within value as the default.
Keep within when the visitor pages through results or changes a filter on the same place.
Index only the plain URL. Any URL with a valid within value gets noindex, follow and a canonical that points at the plain URL.
Mark a city page noindex, follow when the place has no jobs of its own, even at the default distance, so it does not rank on a neighbour's jobs. Read the place's own count from jobCount in board.taxonomy.places.list, not from the widened page.count.
Leave sitemaps on in-place counts; distance views never appear there.

See Styling and formatting for the distance helpers.

Use cursors for load-more and traversal

Echo nextCursor into the next request while preserving the filters. If the first request uses offset, drop it before following a cursor—paginate() does this automatically.

1import { paginate } from '@cavuno/board';
2
3for await (const job of paginate(board.jobs.list, { limit: 100 })) {
4  console.log(job.links.public);
5}

For load-more interfaces, echo nextCursor unchanged. For a background walk, use paginate. Do not translate a cursor into a page number or combine it with a non-zero offset.

Offer weekly alerts without requiring an account

When job alerts are enabled in board.context().features, let a visitor subscribe from the current search state. Anonymous subscriptions require affirmative consent and use double opt-in.

1await board.jobAlerts.subscribe({
2  email,
3  consent: true,
4  frequency: 'weekly',
5  filters: {
6    jobFunctions: selectedJobFunctions,
7    placeSlugs: selectedPlaceSlugs,
8    remoteOptions: selectedRemoteOptions,
9  },
10  context: { source: 'job-search' },
11});

The confirmation link supplies the token for board.jobAlerts.confirm({ token }). Do not imply that the alert is active before confirmation. Digest links should lead to the token-authenticated manage experience where the subscriber can update, unsubscribe, or delete the preference. Weekly is the only supported frequency.

Verify the page

Copy a filtered URL into a new browser and confirm it renders the same selection.
Test no results, invalid filters, a gated count, and a failed search dependency.
Open page 1 and page 2 directly, then follow a cursor from the same filtered result; confirm neither path repeats an item because an old offset remained.
Inspect the canonical and ItemList URLs against the visible cards.
Navigate the pagination using only a keyboard and confirm a crawler can discover page 2 from an anchor href in the initial HTML.
Subscribe anonymously, confirm through the emailed token, and verify that manage and unsubscribe actions work without creating an account.
Open a city page and confirm the default distance (25 mi or 50 km) is applied with no within in the URL. Pick "Exact location only" and a preset, and confirm both URLs are noindex, follow with the plain URL as canonical. Open a region page and confirm it shows no distance menu.

Production notes

Show gated counts honestly when a paywall limits results.
Abort superseded interactive searches.
Keep filters within the Board API’s supported vocabulary.
Use an explicit sort when stable iteration matters; the default relevance ranking can change as jobs or featured status change.
Give the result count or loading region a polite status announcement, preserve focus when filters update, and keep every filter paired with a visible label.

See the Jobs reference for the complete query and response contract.