Install layouts via pnpm

Each layout is also published on npm, and installing via npm is simpler and works with any package manager — that’s the page to use if you just want the latest release (or install all four via plugin, with less manual wiring). This page is for a narrower case: installing straight from this repo’s main branch, ahead of whatever’s currently published, using pnpm’s git-with-subdirectory support.

If you’re cloning or forking the whole project instead — to follow the tutorial, or run the demo site yourself — the packages are already wired together via workspace:*; see Composing layout packages for how that fits together.

Compatibility: every layout works with Astro 6.4.5+ or 7.x, and Starlight 0.40.0–0.41.x, same as installing via npm.

tl;dr

Already know this page, just here to grab the commands for a new project? Run all four:

pnpm add "github:dagilleland/starlight-layouts#main&path:packages/layout-full-width"
pnpm add "github:dagilleland/starlight-layouts#main&path:packages/layout-minimal"
pnpm add "github:dagilleland/starlight-layouts#main&path:packages/layout-with-aside"
pnpm add "github:dagilleland/starlight-layouts#main&path:packages/layout-dashboard"

Only want a subset? Drop whichever lines you don’t need — see Installing more than one. A dedicated wire-up page has the steps for each specific layout — see What you get, and what you still have to do.

This requires pnpm specifically

The syntax below — a git dependency that points at one subdirectory rather than a whole repo — is a pnpm feature (shipped in pnpm v9+), not part of the git-dependency spec that npm and yarn implement, and not currently supported by bun either. If you’re on a different package manager, this page’s approach won’t work as written; see Manually copying layouts instead.

Installing one layout

Each layout lives in its own directory under packages/ in this repo. Point pnpm at the one you want with #<branch>&path:<directory>:

pnpm add "github:dagilleland/starlight-layouts#main&path:packages/layout-dashboard"

Quote the whole value — & is a shell special character, and an unquoted one will do something you don’t want.

This installs @dagilleland/layout-dashboard into your node_modules and adds it to your package.json, using the package’s own name and version (not the value you typed):

package.json (after install)

{
  "dependencies": {
    "@dagilleland/layout-dashboard": "github:dagilleland/starlight-layouts#main&path:packages/layout-dashboard"
  }
}

The four layout directories, if you want a different one:

Layout	path: value
Full-width	packages/layout-full-width
Minimal	packages/layout-minimal
With aside	packages/layout-with-aside
Dashboard	packages/layout-dashboard

Installing more than one

None of the four packages depend on each other, so you can install any subset — each is its own pnpm add line (or its own entry if you’re editing package.json by hand):

pnpm add "github:dagilleland/starlight-layouts#main&path:packages/layout-dashboard"
pnpm add "github:dagilleland/starlight-layouts#main&path:packages/layout-with-aside"

You’re never forced to take all four “as a set.”

What you get, and what you still have to do

This installs the package’s raw source — the same .astro/.ts files you’d find in the repo, no build step, the same way this project’s own app consumes @astrojs/starlight-tailwind. What it does not do is wire the layout into your Starlight site: registering an override component, adding a content-schema field, and so on are still manual steps.

A dedicated page covers exactly that for each layout, with a title on every code block showing which file it goes in: Wire up: full-width, Wire up: minimal, Wire up: with-aside, Wire up: dashboard.

Pin a version instead of tracking main

#main means every pnpm install re-fetches whatever the branch currently points at — fine while you’re getting started, but this project’s main branch will keep changing as the tutorial evolves. Once you’re happy with a layout, pin to a commit SHA instead so your install stops moving:

pnpm add "github:dagilleland/starlight-layouts#a1b2c3d&path:packages/layout-dashboard"

Find a commit’s SHA on the repo’s commit history page. pnpm update won’t touch a SHA-pinned dependency until you deliberately change the SHA yourself.

Removing a layout

Same as any other dependency:

pnpm remove @dagilleland/layout-dashboard

Then remove whatever override/schema wiring you added by hand for it — uninstalling the package doesn’t undo that part.