# Install StepsKit in an Astro site
> Add StepsKit to Astro with the stepskit npm package in a bundled layout script. Covers Astro script directives, view transitions with ClientRouter, and identifying users from middleware.
*Source: https://stepskit.com/docs/install/astro*
For Astro sites, static or server-rendered. Astro's script directives are the
one thing that decides whether this works at all, so read step 1 rather than
skimming it.
## Prerequisites
- Your project API key, from the **Integrations** page in the
[dashboard](/app).
- Astro 4 or 5.
## 1. Install the package
```bash
npm install stepskit
```
Put this in whichever layout wraps every page — typically
`src/layouts/Layout.astro`:
```html
---
// src/layouts/Layout.astro
---
```
### Do NOT add `is:inline` here
This is the Astro rule that trips people up, and with the package it runs the
opposite way to the snippet install.
By default Astro **processes** a bare `
```
```html
```
Useful related rule: Astro won't process a `
```
You lose the queue stub this way. That matters here: an identify call written
inline runs immediately, long before an async engine finishes downloading — so
with this form `window.stepskit` is still undefined and the call is silently
dropped. If you use the external tag, pass user data as `data-user-*`
attributes on it instead of calling `identify()`.
## 2. Identify the user
**This is half the install, not a nice-to-have.** Without an `id`, show-once
capping degrades to a per-tab check and any tour with a "filtered" audience is
hidden outright.
Astro renders on the server, so the natural approach is to resolve the user in
middleware and render the values straight into the page — no client-side auth
round-trip needed.
```ts
// src/middleware.ts
import { defineMiddleware } from "astro:middleware";
export const onRequest = defineMiddleware(async (context, next) => {
context.locals.user = await getUserFromSession(context.cookies);
return next();
});
```
Render the user as JSON, then read it from the same bundled script that calls
`init()`:
```html
---
// src/layouts/Layout.astro
const { user } = Astro.locals;
---
{user && (
)}
```
**Don't reach for `define:vars` here.** It forces `is:inline`, and an inline
script runs at parse time while the bundled one is a deferred module — so the
identify call would fire before `init()` had run. Reading the JSON from inside
the bundled script keeps both in the same execution, in the right order.
For a fully static site with no server render, call `identify` from your own
client-side auth code instead — anywhere you already know who the visitor is.
Pass whatever your user object already carries; every key becomes targetable and
there's no fixed schema to conform to.
## 3. Verify it worked
Load any page of your site, then:
1. **Dashboard** — the project's Integrations page flips to **Connected**.
2. **Console, on a signed-in page** — run
`window.stepskit.validateEnvironment()`. You want a non-null `visitorId` and
a populated `userAttributes`. A null `visitorId` means step 2 never ran.
3. **Network** — `cdn.stepskit.com/stepskit.latest.js` returns `200`.
`validateEnvironment()` also returns a `toursFiltered` table that says exactly
why any given tour isn't showing.
## Astro notes
### View transitions
If you use Astro's client-side router (``, called
`` before Astro 5), navigation no longer reloads the page —
and **scripts do not re-run after a swap**.
For `init()` that's fine and even desirable: it should run once per full page
load, which is exactly what happens. But your `identify` call won't re-run
either, so if the signed-in user can change without a full reload, hook the
lifecycle event:
```html
```
`astro:page-load` fires on the initial load **and** after every swap, which is
why it's the right event rather than `astro:after-swap`.
StepsKit itself needs no help here — it patches `history.pushState` and
`replaceState` and listens for `popstate`, so it sees view-transition navigation
and re-evaluates which tours apply on its own.
### Content Security Policy
Only relevant if your site sets one. Astro's own CSP support is still
experimental, so most projects set these as response headers from their host or
an adapter:
- `script-src`: `https://cdn.stepskit.com`. The package's bundled script needs
no `'unsafe-inline'`; only the `is:inline` snippet form does.
- `connect-src`: `https://stepskit.com`
- `style-src`: `'unsafe-inline'` — **required**. The embed injects its entire
stylesheet as a `