Install

Axis projects are TypeScript CDK apps driven by the axs CLI. Setup is three steps: a Node.js toolchain, a package manager, and one-time authentication against the Axis package registry.

Prerequisites

• Node.js 22 (LTS) or newer. The CDK app, the CLI, and the local toolchain all run on your machine’s Node. (Your deployed Lambda functions have their own runtime setting and default to Node.js 24 — see Lambda Runtimes & the Factory.)

• pnpm 11. Axis is built with pnpm and scaffolds pnpm-ready projects. The easiest install is Corepack, which ships with Node.js:

  corepack enable
  pnpm --version

  npm and yarn work too — every axs flow supports all three, including the npx / pnpm dlx / yarn dlx one-off modes.

• An AWS account and credentials for deploying. Synthesis and unit tests run without AWS access; you only need credentials when you reach AWS Credentials & Bootstrap.

Authenticate with the Axis registry

Axis packages, including the CLI, are hosted on GitHub Packages, so downloads need a GitHub Personal Access Token with the read:packages scope. Create one here (scope pre-selected): https://github.com/settings/tokens/new?scopes=read:packages

There is a bootstrap wrinkle: you need the token to download the CLI, but you need the CLI to run axs auth. The answer is to pass the token inline on the very first run:

# One-time, per machine — pick your package manager
NODE_AUTH_TOKEN=ghp_xxxxxxxxxxxx npx      @axis-tech-co/axs auth
NODE_AUTH_TOKEN=ghp_xxxxxxxxxxxx pnpm dlx @axis-tech-co/axs auth
NODE_AUTH_TOKEN=ghp_xxxxxxxxxxxx yarn dlx @axis-tech-co/axs auth

axs auth validates the token and saves it to ~/.npmrc. Every later command works without the prefix, across all three package managers:

pnpm dlx @axis-tech-co/axs new my-api

Where the token lives (and where it must not)

• ~/.npmrc is the correct home — scoped to package operations, managed by axs auth, and removable with axs auth --reset.
• Never put a token value in a project .npmrc — that file is committed to git. A committed file may reference a secret by variable name; it must never contain one. See Per-project tokens below.
• Never put the token in ~/.bashrc, ~/.zshrc, or any shell config.
• Use a token with only read:packages — never a token with write scopes for daily work.

Per-project tokens

If you work across several repos with a different token per project — or on a machine where a global ~/.npmrc isn’t appropriate — scope the token to the project with a per-directory environment loader such as direnv.

Add the auth line to the project .npmrc. It holds a variable reference, not a secret, so it stays safe to commit:

# .npmrc — committed
@axis-tech-co:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
engine-strict=true

Put the real token in .envrc, which is never committed:

# .envrc — git-ignored
export NODE_AUTH_TOKEN=ghp_xxxxxxxxxxxx

Add .envrc to .gitignore before you write the token into it. Axis does not scaffold that entry, so it is your responsibility:

echo '.envrc' >> .gitignore
direnv allow

Two separate consumers read this setup: your package manager expands ${NODE_AUTH_TOKEN} from the .npmrc line to download packages, and axs reads the environment variable directly. Both are satisfied by the single .envrc export — axs never reads the project .npmrc.

In CI

Set NODE_AUTH_TOKEN as a repository secret — no ~/.npmrc and no interactive step needed:

- run: pnpm install --frozen-lockfile
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Optional: install the CLI globally

The dlx / npx flows never require an install, but a global install gives you a bare axs:

pnpm add -g @axis-tech-co/axs
axs help

Next

You’re ready to create a project.