Skip to content

Astro quickstart

An Astro career site for Northwilds, rendered on the server, with a list of open jobs, job pages and each job's own application form, sent with the Careers SDK.

Tutorial8 min read

In about 15 minutes you build an Astro career site for Northwilds that reads its jobs from Careers Orbit. Visitors filter the open jobs, open one, and apply with the job's own form, CV included. Pages render on your server and the form posts back to them, so the site needs no browser JavaScript.

Tested with: Astro 7.4.7, @astrojs/node 11.1.11, @bifrost-orbit-careers/sdk 0.2.0, Node.js 24.

Before you start

You need:

  • At least one published job in Careers Orbit.
  • A public key (careers_pk_…) from API keys. See API keys.
  • Node.js 22.23.4 or later, which Astro 7 needs.

1Create the project

Shell
npm create astro@latest northwilds-careers -- --template withastro/astro/examples/minimal --install --no-git --yescd northwilds-careersnpx astro add node --yesnpm install @bifrost-orbit-careers/sdkrm src/pages/index.astro

Render every page on the server, so a closed job disappears straight away and the form can post back. Replace astro.config.mjs:

astro.config.mjsJavaScript
// @ts-checkimport { defineConfig } from 'astro/config'import node from '@astrojs/node'export default defineConfig({  output: 'server',  adapter: node({ mode: 'standalone' }),})

Add your settings:

.envShell
CAREERS_API_URL=https://api.bifrostorbit.com/careers/v1CAREERS_PUBLIC_KEY=careers_pk_...

Without a PUBLIC_ prefix, Astro keeps both on the server.

2Add the client

src/lib/careers.tsTypeScript
import { createCareersClient, type CareersApplication, type CareersJob } from '@bifrost-orbit-careers/sdk'export const careers = createCareersClient({  apiUrl: import.meta.env.CAREERS_API_URL,  publicKey: import.meta.env.CAREERS_PUBLIC_KEY,  locale: 'en',})export function readApplication(job: CareersJob, form: FormData) {  const text = (name: string) => String(form.get(name) ?? '').trim()  const file = (name: string) => {    const value = form.get(name)    return value instanceof File && value.size > 0 ? value : undefined  }  const field = (name: keyof CareersJob['form']['fields']) => (job.form.fields[name] === 'off' ? undefined : text(name) || null)  const answers: NonNullable<CareersApplication['answers']> = {}  const questionFiles: Record<string, Blob> = {}  for (const question of job.form.questions) {    const name = `q-${question.id}`    if (question.kind === 'file') {      const upload = file(name)      if (upload) questionFiles[question.id] = upload    } else if (question.kind === 'multiChoice') {      answers[question.id] = form.getAll(name).map(String)    } else {      answers[question.id] = text(name) || null    }  }  const application: CareersApplication = {    firstName: text('firstName'),    lastName: text('lastName'),    email: text('email'),    phone: field('phone'),    coverLetter: field('coverLetter'),    linkedin: field('linkedin'),    location: field('location'),    salaryExpectation: field('salaryExpectation'),    startDate: field('startDate'),    answers,    privacyVersion: Number(text('privacyVersion')),    privacyAccepted: true,    source: 'northwilds.com',  }  return { application, files: { cv: file('cv'), questions: questionFiles } }}
  • createCareersClient reads jobs, filters and the career site, and sends applications. Every call is made from your server.
  • readApplication turns the posted form into the application the delivery API expects. The form in step 5 names each question's field q- and the question's id. Choice answers are option ids, yes or no answers are yes or no, and a question with several choices sends a list.
  • Standard fields the job has switched off are left out. privacyVersion is the version of the privacy notice the candidate saw.
  • source counts the application under northwilds.com in the reports.

3Add a layout

Astro
---// src/layouts/Layout.astrointerface Props {  title: string  description?: string}const { title, description } = Astro.props---<html lang="en">  <head>    <meta charset="utf-8" />    <meta name="viewport" content="width=device-width" />    <title>{title}</title>    {description ? <meta name="description" content={description} /> : null}    <slot name="head" />  </head>  <body>    <header><a href="/careers/">Northwilds careers</a></header>    <main><slot /></main>  </body></html>

4List the jobs

Astro
---// src/pages/careers/index.astroimport Layout from '../../layouts/Layout.astro'import { careers } from '../../lib/careers'const query = Object.fromEntries(Astro.url.searchParams)const [{ items, total }, filters] = await Promise.all([careers.getJobs(query), careers.getFilters()])---<Layout title="Jobs at Northwilds">  <h1>Jobs at Northwilds</h1>  <form method="get">    <input name="q" type="search" placeholder="Search" value={query.q ?? ''} />    <select name="department">      <option value="">All departments</option>      {filters.departments.map((option) => <option value={option.value} selected={query.department === option.value}>{option.label} ({option.count})</option>)}    </select>    <select name="location">      <option value="">All locations</option>      {filters.locations.map((option) => <option value={option.value} selected={query.location === option.value}>{option.label} ({option.count})</option>)}    </select>    <button type="submit">Filter</button>  </form>  <p>{total} {total === 1 ? 'job' : 'jobs'}</p>  <ul>    {items.map((job) => (      <li>        <a href={`/careers/${job.slug}/`}>{job.title}</a>        <p>{[job.department?.name, job.locations.map((location) => location.city).join(', '), job.employmentTypeLabel, job.remoteLabel].filter(Boolean).join(' · ')}</p>        {job.salary ? <p>{job.salary.text}</p> : null}      </li>    ))}  </ul></Layout>
  • getJobs answers the live jobs, newest first, with total. It takes the address's q, department and location as they are.
  • getFilters answers the departments and locations that have live jobs, with counts.
  • salary is only there when you chose to show it, with a ready-made text.

Check it: run npm run dev and open http://localhost:4321/careers/. You see your open jobs, such as "Mountain guide, Lofoten" with "Guiding · Reine · Temporary · On site". Pick Guiding and select Filter: only the guiding jobs stay.

5Build the application form

Each job has its own form: which standard fields it asks for and its questions. This component draws it:

Astro
---// src/components/ApplyForm.astroimport type { CareersJob } from '@bifrost-orbit-careers/sdk'interface Props {  job: CareersJob}const { job } = Astro.propsconst { fields, questions } = job.formconst standard = [  { name: 'phone', label: 'Phone', type: 'tel' },  { name: 'linkedin', label: 'LinkedIn profile', type: 'url' },  { name: 'location', label: 'Where you live', type: 'text' },  { name: 'salaryExpectation', label: 'Salary expectation', type: 'text' },  { name: 'startDate', label: 'Earliest start date', type: 'date' },] as const---<form method="post" enctype="multipart/form-data">  <h2>Apply for this job</h2>  <input type="hidden" name="privacyVersion" value={job.privacy.version} />  <label>First name <input name="firstName" autocomplete="given-name" required /></label>  <label>Last name <input name="lastName" autocomplete="family-name" required /></label>  <label>Email <input name="email" type="email" autocomplete="email" required /></label>  {standard.filter((field) => fields[field.name] !== 'off').map((field) => (    <label>{field.label} <input name={field.name} type={field.type} required={fields[field.name] === 'required'} /></label>  ))}  {fields.cv !== 'off' ? (    <label>CV (PDF or Word, up to 10 MB) <input name="cv" type="file" accept=".pdf,.doc,.docx" required={fields.cv === 'required'} /></label>  ) : null}  {fields.coverLetter !== 'off' ? (    <label>Cover letter <textarea name="coverLetter" rows="6" required={fields.coverLetter === 'required'}></textarea></label>  ) : null}  {questions.map((question) => {    const name = `q-${question.id}`    if (question.kind === 'yesNo') {      return (        <fieldset>          <legend>{question.label}</legend>          <label><input type="radio" name={name} value="yes" required={question.required} /> Yes</label>          <label><input type="radio" name={name} value="no" /> No</label>        </fieldset>      )    }    if (question.kind === 'choice' || question.kind === 'multiChoice') {      const type = question.kind === 'choice' ? 'radio' : 'checkbox'      return (        <fieldset>          <legend>{question.label}</legend>          {question.options.map((option) => (            <label><input type={type} name={name} value={option.id} required={question.required && type === 'radio'} /> {option.label}</label>          ))}        </fieldset>      )    }    if (question.kind === 'longText') {      return <label>{question.label} <textarea name={name} rows="4" required={question.required}></textarea></label>    }    const type = ({ text: 'text', number: 'number', date: 'date', file: 'file' } as const)[question.kind]    return <label>{question.label} <input name={name} type={type} accept={question.kind === 'file' ? '.pdf,.doc,.docx' : undefined} required={question.required} /></label>  })}  <p>{job.privacy.text}</p>  <label><input type="checkbox" name="privacyAccepted" required /> I have read the privacy notice</label>  <button type="submit">Send application</button></form>
  • job.form.fields says for each standard field whether it is required, optional or off.
  • job.form.questions are the job's questions, with their kind: text, longText, choice, multiChoice, yesNo, file, date or number.
  • The privacy notice must be shown and accepted. Careers Orbit refuses an application without it.
  • enctype="multipart/form-data" sends the CV and any files. CVs are PDF or Word documents up to 10 MB.

6Show a job and take applications

Astro
---// src/pages/careers/[slug].astroimport { CareersError } from '@bifrost-orbit-careers/sdk'import ApplyForm from '../../components/ApplyForm.astro'import Layout from '../../layouts/Layout.astro'import { careers, readApplication } from '../../lib/careers'const job = await careers.findJob(Astro.params.slug!)if (!job) return new Response(null, { status: 404 })let error = ''if (Astro.request.method === 'POST') {  const form = await Astro.request.formData()  if (form.get('privacyAccepted') !== 'on') {    error = 'Please read and accept the privacy notice.'  } else {    try {      const { application, files } = readApplication(job, form)      await careers.apply(job.slug, application, files)      return Astro.redirect(`/careers/${job.slug}/?sent=1`, 303)    } catch (caught) {      if (!(caught instanceof CareersError)) throw caught      error = caught.message    }  }}const sent = Astro.url.searchParams.has('sent')const jobPosting = JSON.stringify(job.jobPosting).replace(/</g, '\\u003c')---<Layout title={job.seo.title} description={job.seo.description}>  <script slot="head" type="application/ld+json" set:html={jobPosting} />  <p><a href="/careers/">All jobs</a></p>  <h1>{job.title}</h1>  <p>{[job.department?.name, job.locations.map((location) => location.city).join(', '), job.employmentTypeLabel, job.remoteLabel].filter(Boolean).join(' · ')}</p>  {job.salary ? <p>{job.salary.text}</p> : null}  <div set:html={job.description} />  {sent ? (    <p role="status">Thank you. We have your application and will be in touch.</p>  ) : (    <>      {error ? <p role="alert">{error}</p> : null}      <ApplyForm job={job} />    </>  )}</Layout>
  • findJob answers null for a job that is closed, scheduled or gone, and the page answers 404.
  • The JSON-LD script carries the job's JobPosting data, which Google for Jobs reads. < keeps a < in the text from closing the script early.
  • description is HTML written in Careers Orbit, cleaned before it is sent.
  • A refused application throws a CareersError with a message candidates can read, such as "The privacy notice has just changed. Reload the page and read it again." The form shows it above the fields.
  • After sending, the page redirects to itself with ?sent=1, so reloading never sends the application twice.

Check it: open a job, fill in the form with a test CV and select Send application. The page says "Thank you". In Careers Orbit, the application is in the job's first stage, with the answers and the CV, and its source is northwilds.com.

Next steps

  • Show jobs in other languages: Pass locale: 'de' to createCareersClient, or to each call. Text that isn't translated falls back to your main language.
  • Link candidates' emails to your pages: Set Job addresses under Address and website, such as https://northwilds.com/careers/{slug}/.
  • Keep pages fresh for longer: Cache the answers and clear them from the website webhook.
  • The delivery API: every field, the talent pool and the candidate portal.
  • Troubleshooting: what each error means.

Was this page helpful?

Read next