Builder.io & Astro
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
Builder.io is a visual CMS that supports drag-and-drop content editing for building websites.
PrerequisitesSection titled Prerequisites
To get started, you will need to have the following:
- A Builder account and space - If you don’t have an account yet, sign up for free and create a new space. If you already have a space with Builder, feel free to use it, but you will need to modify the code to match the model name (
blogpost) and custom data fields.
- A Builder API key - This public key will be used to fetch your content from Builder. Read Builder’s guide on how to find your key.
Setting up credentialsSection titled Setting up credentials
To add your Builder API key and your Builder model name to Astro, create a
.env file in the root of your project (if one does not already exist) and add the following variables:
Now, you should be able to use this API key in your project.
If you would like to have IntelliSense for your environment variables, you can create a
env.d.ts file in the
src/ directory and configure
ImportMetaEnv like this:
Your project should now include these files:
Making a blog with Astro and BuilderSection titled Making a blog with Astro and Builder
Creating a model for a blog postSection titled Creating a model for a blog post
The instructions below create an Astro blog using a Builder model (Type: “Section”) called
blogpost that contains two required text fields:
In the Builder app create the model that will represent a blog post: go to the Models tab and click the + Create Model button to create model with the following fields and values:
- Type: Section
- Name: “blogpost”
- Description: “This model is for a blog post”
In your new model use the + New Custom Field button to create 2 new fields:
- Name: “title”
- Required: Yes
- Default value “I forgot to give this a title”
(leave the other parameters as their defaults)
- Name: “slug”
- Required: Yes
- Default value “some-slugs-take-their-time”
(leave the other parameters as their defaults)
Then click the Save button in the upper right.
Setting up the previewSection titled Setting up the preview
To use Builder’s visual editor, create the page
src/pages/builder-preview.astro that will render the special
Then add the following content:
In the above example,
<builder-component> tells Builder where to insert the content from its CMS.
Setting the new route as the preview URLSection titled Setting the new route as the preview URL
Copy the full URL of your preview, including the protocol, to your clipboard (e.g.
Go to the Models tab in your Builder space, pick the model you’ve created and paste the URL from step 1 into the Preview URL field. Make sure the URL is complete and includes the protocol, for example
Click the Save button in the upper right.
Testing the preview URL setupSection titled Testing the preview URL setup
Make sure your site is live (e.g. your dev server is running) and the
/builder-previewroute is working.
In your Builder space under the Content tab, click on New to create a new content entry for your
In the Builder editor that just opened, you should be able to see the
builder-preview.astropage with a big Add Block in the middle.
Creating a blog postSection titled Creating a blog post
- In Builder’s visual editor, create a new content entry with the following values:
- title: ‘First post, woohoo!’
- slug: ‘first-post-woohoo’
- Complete your post using the Add Block button and add a text field with some post content.
- In the text field above the editor, give your entry a name. This is how it will be listed in the Builder app.
- When you’re ready click the Publish button in the upper right corner.
- Create as many posts as you like, ensuring that all content entries contain a
slugas well as some post content.
Displaying a list of blog postsSection titled Displaying a list of blog posts
Add the following content to
src/pages/index.astro in order to fetch and display a list of all post titles, each linking to its own page:
Fetching via the content API returns an array of objects containing data for each post. The
fields query parameter tells Builder which data is included (see highlighted code).
title should match the names of the custom data fields you’ve added to your Builder model.
posts array returned from the fetch displays a list of blog post titles on the home page. The individual page routes will be created in the next step.
Go to your index route and you should be able to see a list of links each with the title of a blog post!
Displaying a single blog postSection titled Displaying a single blog post
Create the page
src/pages/posts/[slug].astro that will dynamically generate a page for each post.
This file must contain:
getStaticPaths()function to fetch
sluginformation from Builder and create a static route for each blog post.
fetch()to the Builder API using the
slugidentifier to return post content and metadata (e.g. a
<Fragment />in the template to render the post content as HTML.
Each of these is highlighted in the following code snippet.
Now when you click on a link on your index route, you will be taken to the individual blog post page.
Publishing your siteSection titled Publishing your site
To deploy your website, visit our deployment guides and follow the instructions for your preferred hosting provider.
Rebuild on Builder changesSection titled Rebuild on Builder changes
If your project is using Astro’s default static mode, you will need to set up a webhook to trigger a new build when your content changes. If you are using Netlify or Vercel as your hosting provider, you can use its webhook feature to trigger a new build whenever you click Publish in the Builder editor.
NetlifySection titled Netlify
- Go to your site dashboard, then Site Settings and click on Build & deploy.
- Under the Continuous Deployment tab, find the Build hooks section and click on Add build hook.
- Provide a name for your webhook and select the branch you want to trigger the build on. Click on Save and copy the generated URL.
VercelSection titled Vercel
- Go to your project dashboard and click on Settings.
- Under the Git tab, find the Deploy Hooks section.
- Provide a name for your webhook and the branch you want to trigger the build on. Click Add and copy the generated URL.
Adding a webhook to BuilderSection titled Adding a webhook to Builder
- In your Builder dashboard, go into your
blogpostmodel. Under Show More Options, select Edit Webhooks at the bottom.
- Add a new webhook by clicking on Webhook. Paste the URL generated by your hosting provider into the Url field.
- Click on Show Advanced under the URL field and toggle the option to select Disable Payload. With the payload disabled, Builder sends a simpler POST request to your hosting provider, which can be helpful as your site grows. Click Done to save this selection.
With this webhook in place, whenever you click the Publish button in the Builder editor, your hosting provider rebuilds your site - and Astro fetches the newly published data for you. Nothing to do but lean back and pump out that sweet sweet content!
Official resourcesSection titled Official resources
- Check out the official Builder.io starter project, which uses Astro and SolidJS.
- Builder’s API explorer can help if you need to troubleshoot your API calls.
Community resourcesSection titled Community resources
- Read Connecting Builder.io’s Visual CMS to Astro by Yoav Ganbar.