Astro

Getting Started with Strife and Astro

This guide walks you through how to integrate Strife CMS into your Astro project using TypeScript.

1. Create a new Astro project

Start by creating a fresh Astro project:

npm create astro@latest

Follow the prompts to scaffold your site.

2. Install the Strife Astro Integration

Inside your Astro project, install the Strife integration:

npx astro add @strifeapp/astro

After running this, your astro.config.mjs will be updated automatically:

import { defineConfig } from 'astro/config';
import strife from '@strifeapp/astro';

export default defineConfig({
  integrations: [strife()],
  output: 'server',
});

Strife requires output: 'server' because content is fetched at request time. The integration sets this automatically on install, and also pulls in @strifeapp/types so TypeScript users get full type safety without any extra install step.

From @strifeapp/astro 1.6.0 the integration caps the RavenDB client's in-memory response cache at 8 MiB (set strife({ httpCache: { maxBytes } }) to change it). If your project also lists ravendb as its own dependency, keep it at 7.2.3 or later: older clients cannot be given a byte budget, so the integration limits them to 500 cached responses and logs a warning.

3. Define your first Collection and Template

In Strife, content is structured via Collections and Templates. Each template describes the fields available for a collection item.

A typical site has a mix of singleton templates (one document per project — e.g. a Home page or Global Settings) and multi-instance templates (many documents — e.g. blog posts or product pages). Strife controls this with the composable field on the template.

For more information on how templates and collections work, see the full Strife Templates & Collections documentation.

Start with a Home template for your site's root page. Create src/collections/Home.ts:

import { type Template } from '@strifeapp/types';

const Home: Template = {
  displayName: 'Home',
  collection: 'Homes',
  templateType: 'dt',
  normalizedName: 'home',
  composable: false,  // singleton — only one Home document per project
  editors: [
    {
      label: 'Heading',
      editor: { name: 'str-input', type: 'text', propertyName: 'heading' },
    },
    {
      label: 'Description',
      editor: { name: 'str-textarea', type: 'text', propertyName: 'description' },
    },
  ],
};

export default Home;

Then add a Pages template for any other content — about, contact, marketing pages, anything that isn't a one-off. Create src/collections/Pages.ts:

import { type Template } from '@strifeapp/types';

const Pages: Template = {
  displayName: 'Page',
  collection: 'Pages',
  templateType: 'dt',
  normalizedName: 'page',
  composable: true,  // multi-instance — editors can create many Pages
  editors: [
    {
      label: 'Heading',
      editor: { name: 'str-input', type: 'text', propertyName: 'heading' },
    },
    {
      label: 'Description',
      editor: { name: 'str-textarea', type: 'text', propertyName: 'description' },
    },
  ],
};

export default Pages;

The two templates illustrate the contrast: Home has composable: false (only one document allowed), while Pages has composable: true (editors can create many). Use composable: false for templates that should only ever have one document — Home, Global Settings, Footer config, etc. — and composable: true for repeatable content. See the templates reference for the full list of template properties.

4. Register your Collection

Import your collection and register it in your Strife integration at astro.config.mjs

import { defineConfig } from 'astro/config';
import strife from '@strifeapp/astro';
import Home from './src/collections/Home';
import Pages from './src/collections/Pages';

export default defineConfig({
  integrations: [strife({
    collections: [Home, Pages]
  })],
  output: 'server',
});

5. Create your Content Types

Define TypeScript interfaces matching each collection for strong typing when querying:

import { type Content } from '@strifeapp/types';

export type Home = Content & {
  heading: string;
  description: string;
};

export type Page = Content & {
  heading: string;
  description: string;
};

In real projects these two might diverge — Home could have its own hero structure, Pages might be more flexible — but for the tutorial they share the same shape.

6. Add your Strife Credentials

Create a .env file in your project root with the credentials provided for your team:

# .env

# RavenDB client certificate — base64-encoded PFX bundle
STRIFE_CERTIFICATE=...

# Password protecting the PFX certificate above
STRIFE_CERTIFICATE_PASSWORD=...

# Comma-separated list of RavenDB node URLs
STRIFE_DATABASE_URLS=https://a.example.strife.ravendb.cloud

# Name of your team's RavenDB database
STRIFE_DATABASE=...

# Your team's unique identifier
TEAM_ID=...

# Signing secret used for preview and webhook payloads
SECRET=...

7. Enable TypeScript Module Declarations

To support type-safe access to Strife's document store, update or create src/env.d.ts (recent Astro starters auto-generate types in .astro/ and don't ship a stub env.d.ts):

/// <reference types="astro/client" />

declare module 'strife:store' {
  import type { IDocumentSession, IDocumentStore } from 'ravendb';
  export const store: IDocumentStore;
  export { IDocumentSession };
}

8. Query Content from Strife

You can now query your content directly from RavenDB via Strife. The same query pattern works for both singleton and multi-instance templates — it matches by URL:

import { store } from 'strife:store';
import type { Home } from '../collections/Home';

const session: IDocumentSession = store.openSession();

// Returns the Home document for url='/'.
// For other URLs ('/about', '/contact', etc.), the same query returns
// whichever Page document has that url.
const home: Home = (await session
  .query({ indexName: 'Content/ByUrl' })
  .whereEquals('url', '/')
  .selectFields(['heading', 'description'])
  .firstOrNull()) as Home;

9. Deploy your templates

Templates and the Content/ByUrl query index are deployed with Strife CLI:

npm install --save-dev @strifeapp/cli @strifeapp/strife
npx strife login
npx strife link

The templates you registered as Template objects in step 4 aren't picked up by strife push directly — push deploys schemas written with defineType. If you're following this tutorial's Template-object approach, create your templates directly in Strife Studio instead (Settings → Templates) rather than via push, or see the CLI reference for defining them in code as defineType schemas instead of the Template objects used in steps 3–4.

Once your templates exist (via Studio or defineType + push), start the dev server as usual:

npm run dev

and visit the URL Astro prints (e.g. http://localhost:4321/).

10. Add live preview (optional)

Strife Studio includes a preview iframe that mirrors your site as content is edited. With the integration installed, your islands can subscribe to updates:

<!-- src/components/Hero.svelte -->
<script lang="ts">
  import { subscribe } from '@strifeapp/strife';
  import { onMount } from 'svelte';

  let { initial } = $props<{ initial: { heading: string; description: string } }>();
  let data = $state(initial);

  onMount(() => subscribe((next) => { data = next; }));
</script>

<h1>{data.heading}</h1>
<p>{data.description}</p>

This requires loading @strifeapp/strife eagerly in your root layout (otherwise the iframe handshake completes before subscribers are ready). For full setup, the data-shape reference, and framework-agnostic patterns, see Custom Live Preview implementation.

Snapshots (optional)

Editors can hand a reviewer without a Strife account a preview link — https://example.com/snapshot/{token} — that shows a frozen, unpublished version of a document on your site for 7 days. The integration's snapshot middleware resolves the link; you add the page that renders it. Copy the package's templates/snapshot-page.astro to src/pages/snapshot/[token].astro:

---
export const prerender = false;              // rendered on demand — never prebuilt
import Layout from '../../layouts/Layout.astro';

const { name, expiresAt, locale, content } = Astro.locals.snapshot!;
---
<Layout title={content.displayName ?? 'Preview'}>
  <aside role="status">{name ? `Preview “${name}”` : 'Preview'} — expires {expiresAt.toISOString()}</aside>
  <h1>{content.heading}</h1>
</Layout>

Expired, revoked or unknown links render your 404 page. The route needs a Content/ByUrl index built from the @strifeapp/strife release that ships snapshots (run strife push after updating), and the name must be rendered as text only. Locale prefixes, snapshot.fields, sites that resolve locale in their own middleware, and the CDN/analytics rules are in the Snapshots reference.

11. Choose a deployment adapter

astro dev works out of the box. For production builds (astro build), Astro needs an adapter that matches your deploy target. Strife doesn't require a specific one — pick whichever suits your hosting:

See Astro's deploy guides for the full list and configuration details.

After installing an adapter, your astro.config.mjs will look something like:

import { defineConfig } from 'astro/config';
import strife from '@strifeapp/astro';
import node from '@astrojs/node';           // or vercel, netlify, cloudflare…
import Homes from './src/collections/Homes';

export default defineConfig({
  integrations: [strife({ collections: [Homes] })],
  output: 'server',
  adapter: node({ mode: 'standalone' }),     // adapter-specific options vary
});

Push your repository to your chosen host and your Strife-powered Astro site is live.