Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
161 lines (115 loc) · 5.26 KB

CONTRIBUTING.md

File metadata and controls

161 lines (115 loc) · 5.26 KB
Raw

Contributing

Commands

These docs are built using [Astro][astro] and [Starlight][starlight]. All commands are run from the root of the project, from a terminal:

Command Action
npm ci Installs dependencies
npm run dev Starts local dev server at localhost:4321
npm run build Build your production site to ./dist/
npm run preview Preview your build locally, before deploying
npm run astro ... Run CLI commands like astro add, astro check
npm run astro -- --help Get help using the Astro CLI

Tests

We use Playwright for browser testing. The tests are located in the ./tests directory.

These instructions assume you are already running in the provided devcontainer.

Run Playwright locally

Playwright will automatically detect if your local dev server is already running. If your local dev server isn't running, Playwright will build and preview the site for testing.

To open Playwright in UI mode:

npm run pw:open

To run Playwright tests in the terminal:

npm run pw:run

Updating screenshots

We use screenshot testing to ensure visual consistency. If you make intentional changes you will likely need to update the stored screenshots. To do so run:

npm run pw:run -- --update-snapshots=changed

This will update only the screenshots for tests that have changed. On rare occasions you may want to update all screenshots, which you can do with:

npm run pw:run -- --update-snapshots=all

Adding content

Add a framework

  • in lib/prefs.ts add the key and label to the frameworks array
  • in src/components/icons/tech/$Framework.tsx add an icon
  • in src/components/FrameworkSwitcher.tsx reference the icon in the frameworkIcon object
  • in src/components/FrameworkLinks.tsx add a case "$framework" for the icon
  • in src/content/docs/get-started.mdx add to frameworks and titleByFramework, define steps, and use those steps where appropriate
  • in src/content/docs/reference/$framework.mdx write a reference guide
  • in src/components/SdkReferenceLinkByFramework.mdx and src/lib/sidebar.ts link that reference
  • in public/llms-full.txt under SDKs link that reference

Add framework options to a page

To add a framework option to a page such as src/content/docs/get-started.mdx:

  • Add your framework to the frontmatter frameworks

  • Add the page title to the frontmatter titleByFramework

  • Use <SlotByFramework /> or <TextByFramework /> components to display content for the currently selected framework:

    <SlotByFramework client:load>
  ...
  <SomeContent slot="$framework" />
</SlotByFramework>

    This will make <SomeContent /> only visible when the new framework is selected.

In-page framework links

We provide a framework selection component for each page including the docs home. However the docs home is the only page that always display the links. The other pages will hide the component if a framework is already selected.

In home:

<FrameworkLinks
  title="Get started"
  path="/get-started"
  alwaysShow
  client:load
/>

Internal links

Internal links between docs pages must use <Link.Page> or <Link.ToSdk> components, not plain markdown links. This enables framework-aware routing.

import { Link } from "@/components/link";

{/* Internal page link */}
See <Link.Page href="/environment">Environment variables</Link.Page>.

{/* SDK-specific link (backwards compatible with ?f= framework switcher) */}
See the <Link.ToSdk href="/get-started" sdk="next">quick start</Link.ToSdk>.

Rules

  • Import once per file: import { Link } from "@/components/link";
  • href is the root-relative path without domain (e.g. /environment#arcjet-env)
  • Link text must be on a single line — newlines inside <Link.*>…</Link.*> break MDX rendering
  • External links and [Arcjet Dashboard](https://app.arcjet.com) style links remain plain markdown

Background

Older pages used markdown reference-style links ([text][ref-id]) with definitions at the bottom of the file. Those have been replaced. Any remaining plain markdown internal links (e.g. [text](/path)) should be converted to <Link.Page> or <Link.ToSdk> when editing a file.

Dependency updates

We maintain a 30 day cooldown period for dependency versions to mitigate supply chain risks. This cooldown period does not include Arcjet maintained packages or security updates.

Update all Arcjet packages to their latest versions

npx --no -- npm-check-updates --interactive --workspaces --filter 'arcjet, @arcjet/*, nosecone, @nosecone/*' --target latest
npm up arcjet "@arcjet/*" nosecone "@nosecone/*" --workspaces

Update all dependencies to their cooldown minor versions

npx --no -- npm-check-updates --interactive --workspaces --cooldown 30 --target minor

Update all dependencies to their cooldown major versions

npx --no -- npm-check-updates --interactive --workspaces --cooldown 30 --target @latest