Make your Astro project dynamic

Connect to Prepr

To connect directly to Prepr CMS, add a fetch helper that sends GraphQL queries to the Prepr API.

1. Stop the localhost website server (CTRL-C) if it’s running and execute the following command in the terminal to install GraphQL packages:

   npm add @graphql-typed-document-node/core graphql

2. Create a lib folder in the src directory. Then create a file called prepr.ts in this folder. Copy the following code to this file to set up the fetch helper:

   ./src/lib/prepr.ts

   import { PREPR_GRAPHQL_URL } from 'astro:env/server';
   import { print } from 'graphql';
   import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
    
   export async function prepr<TResult, TVariables>(
       document: TypedDocumentNode<TResult, TVariables>,
       variables: TVariables,
       headers: Record<string, string> = {},
   ): Promise<TResult> {
       const response = await fetch(PREPR_GRAPHQL_URL, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json', ...headers },
       body: JSON.stringify({ query: print(document), variables }),
       });
       if (!response.ok) {
       throw new Error(`Prepr GraphQL request failed: ${response.status} ${response.statusText}`);
       }
       const { data, errors } = await response.json();
       if (errors?.length) throw new Error(errors[0].message);
       return data;
   }

3. We recommend using environment variables to store sensitive information like access tokens. To add environment variables, create a .env file in the root directory of your project and add the access token like this:

   ./.env

   PREPR_GRAPHQL_URL=<YOUR-PREPR-GRAPHQL-URL>

4. Replace the placeholder value <YOUR-PREPR-GRAPHQL-URL> with the API URL of an access token from Prepr. Get an access token by logging into your Prepr account:
   a. Click the icon and choose the Access tokens option to view all the access tokens.
   b. Click to open the GraphQL Production access token, and copy the API URL to only retrieve published content items on your site for now. c. Paste the copied API URL in your .env file.

5. Declare the PREPR_GRAPHQL_URL variable in your astro.config.mjs so Astro validates and types it. At this stage, also add the image.domains entry to fetch page images from the Prepr demo environment.

   ./astro.config.mjs

   // @ts-check
   import { defineConfig, envField, fontProviders } from 'astro/config';
   import node from '@astrojs/node';
   import tailwindcss from '@tailwindcss/vite';
    
   export default defineConfig({
     // Render every request on the server: personalization and A/B testing
     // depend on per-visitor request headers.
     output: 'server',
     adapter: node({ mode: 'standalone' }),
     fonts: [
       {
         provider: fontProviders.google(),
         name: 'Ubuntu',
         cssVariable: '--font-ubuntu',
         weights: [400, 700],
         subsets: ['latin'],
       },
     ],
     vite: {
       plugins: [tailwindcss()],
     },
     image: {
       // Domain of the Acme Lease demo images. Add your own asset domain here.
       domains: ['demo-patterns.stream.prepr.io'],
     },
     env: {
       schema: {
         PREPR_GRAPHQL_URL: envField.string({ context: 'server', access: 'secret' }),
       },
     },
   });

6. Execute the following command to restart the server and refresh your page in the browser.

   npm run dev

If your website runs without errors, then the setup above was done correctly. Now that Astro can reach the Prepr API, you can retrieve content from Prepr.

Before we create a query to retrieve content, let’s follow some best practices for TypeScript and install a GraphQL code generator.

Install a code generator

In this step, you’ll install a GraphQL code generator to generate TypeScript types automatically for your queries and keep these up to date with any schema changes. Check out the TypeScript best practices doc for more details. In the meantime, follow the steps below to install the GraphQL code generator.

1. Stop the localhost website server (CTRL-C) if it’s running and execute the following commands in your terminal:

   npm add -D @graphql-codegen/cli @graphql-codegen/client-preset @graphql-codegen/introspection
   npm add -D dotenv
   npm add -D @astrojs/check typescript

   When you run the build script, it runs astro check, which needs @astrojs/check and typescript installed

2. Once done, create a new file, codegen.ts in the root of your project. Update it with the code below.

   ./codegen.ts

   import 'dotenv/config';
   import type { CodegenConfig } from '@graphql-codegen/cli';
    
   const config: CodegenConfig = {
     overwrite: true,
     schema: process.env.PREPR_GRAPHQL_URL,
     documents: ['src/queries/**/*.graphql'],
     generates: {
       'src/gql/': {
         preset: 'client',
         presetConfig: { fragmentMasking: false },
         // Astro's strict tsconfig enables verbatimModuleSyntax.
         config: { useTypeImports: true },
       },
       './graphql.schema.json': { plugins: ['introspection'] },
     },
   };
    
   export default config;

3. To complete the codegen installation, update the scripts block in your package.json so build runs codegen and a type check before astro build, and add a codegen script. Leave the rest of your package.json (name, version, dependencies) as-is — only the scripts block changes:

   ./package.json

   {
       ...
       "scripts": {
       "dev": "astro dev",
       "build": "npm run codegen && astro check && astro build",
       "start": "node --env-file-if-exists=.env ./dist/server/entry.mjs",
       "preview": "astro preview",
       "astro": "astro",
       "codegen": "graphql-codegen --config codegen.ts"
       }
       ...
   }

   The built server doesn’t load .env on its own. --env-file-if-exists=.env tells Node to load it, so PREPR_GRAPHQL_URL and other secrets are available when you run npm start after npm run build.

   Host-provided environment variables, for example, in a deployment platform, still take precedence over .env.

4. Execute the following command to restart the server and refresh your page in the browser to make sure the fetch helper is set up correctly:

   npm run dev

If your website runs without errors, then the setup above was done correctly. Now you can add a query to your project.

Add a GraphQL query

Once the GraphQL code generator is installed, you can add a query to get the content for your home page from Prepr.

If you’re using preloaded demo data in your Prepr environment as mentioned in the Prerequisites, you should have a Homepage content item like in the images below. The Homepage has all the elements of the page in a Stack field. The stack makes it easy for an editor to set up their page content in a flexible structure for the front end.

Follow the steps below to add a query to retrieve the id, title, slug, and a stack containing the hero and feature sections with their own fields:

1. Create a queries folder in the src directory of your project and create a file named get-page-by-slug.graphql.
2. Add the following queries in the queries folder to retrieve a page by its slug:

# The GetPageBySlug query uses a slug value from the input parameter to retrieve a specific page
query GetPageBySlug($slug: String) {
    Page(slug: $slug) {
        title
        _id
        content {
            __typename
            ... on Hero {
                ...Hero
            }
            ... on Feature {
                ...Feature
            }
        }
    }
}

fragment Button on Button {
    button_type
    text
    external_url
    link {
        ... on Category {
            _slug
        }
        ... on Page {
            _slug
        }
        ... on Post {
            _slug
        }
    }
}

fragment Feature on Feature {
    _id
    heading
    sub_heading
    button {
        ...Button
    }
    _context {
        variant_key
    }
    image_position
    image {
        url(width: 870, height: 570)
    }
}

fragment Hero on Hero {
    _id
    sub_heading
    image {
        url(preset: "Hero", width: 2000)
        height
        width
    }
    _context {
        variant_key
    }
    heading
    buttons {
        ...Button
    }
}

Generate TypeScript types

1. Now that the query is created, stop the localhost website server (CTRL-C) and generate the TypeScript types by running the following command in the terminal:

   npm run codegen

2. If the command is successful you’ll see new files in the src/gql folder, including graphql.ts. Check out the TypeScript doc for more details.

3. Test the query by updating the [...slug].astro file. The code below executes the query and returns early with a 404 rewrite if the page doesn’t exist.

   ./src/pages/[...slug].astro

   ---
   import Layout from '../layouts/Layout.astro';
   import Hero from '../components/sections/Hero.astro';
   import Feature from '../components/sections/Feature.astro';
   import { prepr } from '../lib/prepr';
   import { GetPageBySlugDocument } from '../gql/graphql';
    
   // The home page has no slug in the URL; in Prepr its slug is '/'.
   const slug = Astro.params.slug ?? '/';
   const data = await prepr(GetPageBySlugDocument, { slug });
    
   if (!data.Page) return Astro.rewrite('/404');
   const page = data.Page;
   ---
    
   <Layout>
       <Hero />
       <Feature />
       <Feature align="right" />
       <Feature />
   </Layout>

4. You need a page to rewrite to when the slug isn’t found. Create a new page called 404.astro:

---
import Layout from '../layouts/Layout.astro';
 
Astro.response.status = 404;
---
 
<Layout>
  <div class="mx-auto max-w-8xl p-spacing py-20 text-center text-secondary-700">
    <h1 class="text-5xl font-medium">404</h1>
    <p class="mt-4">This page could not be found.</p>
  </div>
</Layout>

Now that the query has been created and retrieves the data successfully, fetch and show the specific page content from the query results.

Fetch page content

To view the Prepr content in your website, you need to fetch the page elements. As mentioned previously, the page has elements in a Stack field. You’ll fetch two components, a Hero section and Feature sections in the stack.

1. Next, update your components to display data dynamically.

---
import { Image } from 'astro:assets';
import type { HeroFragment } from '../../gql/graphql';
import Button from '../Button.astro';
 
interface Props {
  item: HeroFragment;
}
 
const { item } = Astro.props;
const image = item.image;
---
 
<section class="bg-primary-50">
  <div class="mx-auto max-w-8xl p-spacing flex flex-col items-center md:flex-row gap-8 py-10 lg:py-20">
    <div class="basis-6/12">
      <h1 class="text-mb-5xl lg:text-7xl text-secondary-700 font-medium break-words text-balance">{item.heading}</h1>
      <p class="text-secondary-500 lg:text-lg mt-4 lg:mt-6 text-balance">{item.sub_heading}</p>
      <div class="flex gap-4 mt-8 xl:mt-10">
        <div>
          <a href="#"><Button>{item.buttons[0]?.text}</Button></a>
        </div>
      </div>
    </div>
    <div class="basis-6/12 relative flex justify-end items-center">
      <div class="z-10 flex items-center aspect-[20/17] w-9/12 overflow-hidden justify-center absolute top-1/2 left-1/2 transform -translate-x-1/2 -translate-y-1/2">
        {image?.url && <Image src={image.url} alt="Hero Image" width={720} height={360} class="object-cover rounded-2xl" />}
      </div>
      <div class="w-9/12 aspect-[20/17] bg-primary-100 rounded-3xl right-0 top-0 z-0"></div>
    </div>
  </div>
</section>

---
import { Image } from 'astro:assets';
import type { FeatureFragment } from '../../gql/graphql';
import Button from '../Button.astro';
 
interface Props {
  item: FeatureFragment;
}
 
const { item } = Astro.props;
---
 
<section class="bg-primary-50">
  <div class="mx-auto max-w-8xl p-spacing py-10 lg:py-10 xl:py-20">
    <div class="flex flex-col items-start md:items-center md:flex-row gap-8 xl:gap-28 text-secondary-700">
      {item.image_position === 'LEFT' && item.image?.url && (
        <div class="order-first md:order-none basis-1/2">
          <Image src={item.image.url} alt="Feature image" width={800} height={300} class="rounded-2xl w-full aspect-[29/19] object-cover" />
        </div>
      )}
      <div class="basis-1/2">
        <h2 class="text-mb-4xl lg:text-5xl font-medium text-secondary-700 text-balance">{item.heading}</h2>
        <p class="text-lg mt-4 xl:mt-6 font-medium text-balance">{item.sub_heading}</p>
        <a href="#"><Button>{item.button?.text}</Button></a>
      </div>
      {item.image_position === 'RIGHT' && item.image?.url && (
        <div class="order-first md:order-none basis-1/2">
          <Image src={item.image.url} alt="Feature image" width={800} height={300} class="rounded-2xl w-full aspect-[29/19] object-cover" />
        </div>
      )}
    </div>
  </div>
</section>

2. Now update [...slug].astro to fetch and render the elements from the stack:

---
import Layout from '../layouts/Layout.astro';
import Hero from '../components/sections/Hero.astro';
import Feature from '../components/sections/Feature.astro';
import { prepr } from '../lib/prepr';
import { GetPageBySlugDocument } from '../gql/graphql';
 
// The home page has no slug in the URL; in Prepr its slug is '/'.
const slug = Astro.params.slug ?? '/';
const data = await prepr(GetPageBySlugDocument, { slug });
 
if (!data.Page) return Astro.rewrite('/404');
const page = data.Page;
---
 
<Layout>
  {page.content.map((element) => {
    if (element.__typename === 'Hero') return <Hero item={element} />;
    if (element.__typename === 'Feature') return <Feature item={element} />;
  })}
</Layout>

Now when you view the website on your localhost, you’ll see something like the image below: