Drupal & Astro
Drupal is an open-source content management tool.
Prerequisites
Section titled PrerequisitesTo get started, you will need to have the following:
-
An Astro project - If you don’t have an Astro project yet, our Installation guide will get you up and running in no time.
-
A Drupal site - If you haven’t set up a Drupal site, you can follow the official guidelines Installing Drupal.
Integrating Drupal with Astro
Section titled Integrating Drupal with AstroInstalling the JSON:API Drupal module
Section titled Installing the JSON:API Drupal moduleTo be able to get content from Drupal you need to enable the Drupal JSON:API module.
- Navigate to the Extend page
admin/modules
via the Manage administrative menu - Locate the JSON:API module and check the box next to it
- Click Install to install the new module
Now you can make GET
requests to your Drupal application through JSON:API.
Adding the Drupal URL in .env
Section titled Adding the Drupal URL in .envTo add your Drupal URL to Astro, create a .env
file in the root of your project (if one does not already exist) and add the following variable:
Restart the dev server to use this environment variable in your Astro project.
Setting up Credentials
Section titled Setting up CredentialsBy default, the Drupal JSON:API endpoint is accessible for external data-fetching requests without requiring authentication. This allows you to fetch data for your Astro project without credentials but it does not permit users to modify your data or site settings.
However, if you wish to restrict access and require authentication, Drupal provides several authentication methods including:
- Basic Authentication
- API Key-based authentication
- Access Token/OAuth-based authentication
- JWT Token-based authentication
- Third-Party Provider token authentication
You can add your credentials to your .env
file.
.env
files in Astro.
Your root directory should now include this new files:
- .env
- astro.config.mjs
- package.json
Installing dependencies
Section titled Installing dependenciesJSON:API requests and responses can often be complex and deeply nested. To simplify working with them, you can use two npm packages that streamline both the requests and the handling of responses:
JSONA
: JSON API v1.0 specification serializer and deserializer for use on the server and in the browser.Drupal JSON-API Params
: This module provides a helper Class to create the required query. While doing so, it also tries to optimise the query by using the short form, whenever possible.
Fetching data from Drupal
Section titled Fetching data from DrupalYour content is fetched from a JSON:API URL.
Drupal JSON:API URL Sructure
Section titled Drupal JSON:API URL SructureThe basic URL structure is: /jsonapi/{entity_type_id}/{bundle_id}
The URL is always prefixed by jsonapi
.
- The
entity_type_id
refers to the Entity Type, such as node, block, user, etc. - The
bundle_id
refers to the Entity Bundles. In the case of a Node entity type, the bundle could be article. - In this case, to get the list of all articles, the URL will be
[DRUPAL_BASE_URL]/jsonapi/node/article
.
To retrieve an individual entity, the URL structure will be /jsonapi/{entity_type_id}/{bundle_id}/{uuid}
, where the uuid is the UUID of the entity. For example the URL to get a specific article will be of the form /jsonapi/node/article/2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e
.
Retrieving only certain fields
Section titled Retrieving only certain fieldsRetrieve only certain field by adding the Query String field to the request.
GET: /jsonapi/{entity_type_id}/{bundle_id}?field[entity_type]=field_list
Examples:
/jsonapi/node/article?fields[node--article]=title,created
/jsonapi/node/article/2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e?fields[node--article]=title,created,body
Filtering
Section titled FilteringAdd a filter to your request by adding the filter Query String.
The simplest, most common filter is a key-value filter:
GET: /jsonapi/{entity_type_id}/{bundle_id}?filter[field_name]=value&filter[field_other]=value
Examples:
/jsonapi/node/article?filter[title]=Testing JSON:API&filter[status]=1
/jsonapi/node/article/2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e?fields[node--article]=title&filter[title]=Testing JSON:API
You can find more query options in the JSON:API Documentation.
Building a Drupal query
Section titled Building a Drupal queryAstro components can fetch data from your Drupal site by using drupal-jsonapi-params
package to build the query.
The following example shows a component with a query for an “article” content type that has a text field for a title and a rich text field for content:
You can find more querying options in the Drupal JSON:API Documentation
Making a blog with Astro and Drupal
Section titled Making a blog with Astro and DrupalWith the setup above, you are now able to create a blog that uses Drupal as the CMS.
Prerequisites
Section titled Prerequisites-
An Astro project with
JSONA
andDrupal JSON-API Params
installed. -
A Drupal site with at least one entry - For this tutorial we recommend starting with a new Drupal site with Standard installation.
In the Content section of your Drupal site, create a new entry by clicking the Add button. Then, choose Article and fill in the fields:
- Title:
My first article for Astro!
- Alias:
/articles/first-article-for astro
- Description:
This is my first Astro article! Let's see what it will look like!
Click Save to create your first Article. Feel free to add as many articles as you want.
- Title:
Displaying a list of articles
Section titled Displaying a list of articles-
Create
src/types.ts
if it does not already exist and add two new interfaces calledDrupalNode
andPath
with the following code. These interfaces will match the fields of your article content type in Drupal and the Path fields. You will use it to type your article entries response.Your src directory should now include the new file:
- .env
- astro.config.mjs
- package.json
Directorysrc/
- types.ts
-
Create a new file called
drupal.ts
undersrc/api
and add the following code:This will import the required libraries such as
Jsona
to deserialize the response,DrupalJsonApiParams
to format the request url and the Node and Jsona types. It will also get thebaseUrl
from the.env
file.Your src/api directory should now include the new file:
- .env
- astro.config.mjs
- package.json
Directorysrc/
Directoryapi/
- drupal.ts
- types.ts
-
In that same file, create the
fetchUrl
function to make the fetch request and deserialize the response. -
Create the
getArticles()
function to get all published articles.Now you can use the function
getArticles()
in an.astro
component to get all published articles with data for each title, body, path and creation date. -
Go to the Astro page where you will fetch data from Drupal. The following example creates an articles landing page at
src/pages/articles/index.astro
.Import the necessary dependencies and fetch all the entries from Drupal with a content type of
article
usinggetArticles()
while passing theDrupalNode
interface to type your response.This fetch call using getArticles() will return a typed array of entries that can be used in your page template.
Your
src/pages/
directory should now include the new file, if you used the same page file:- .env
- astro.config.mjs
- package.json
Directorysrc/
Directoryapi/
- drupal.ts
Directorypages/
Directoryarticles/
- index.astro
- types.ts
-
Add content to your page, such as a title. Use
articles.map()
to show your Drupal entries as line items in a list.
Generating individual blog posts
Section titled Generating individual blog postsUse the same method to fetch your data from Drupal as above, but this time, on a page that will create a unique page route for each article.
This example uses Astro’s default static mode, and creates a dynamic routing page file with the getStaticPaths()
function. This function will be called at build time to generate the list of paths that become pages.
-
Create a new file
src/pages/articles/[path].astro
and import theDrupalNode
interface andgetArticle()
fromsrc/api/drupal.ts
. Fetch your data inside agetStaticPaths()
function to create routes for your blog.Your src/pages/articles directory should now include the new file:
- .env
- astro.config.mjs
- package.json
Directorysrc/
Directoryapi/
- drupal.ts
Directorypages/
Directoryarticles/
- index.astro
- [path].astro
- types.ts
-
In the same file, map each Drupal entry to an object with a
params
andprops
property. Theparams
property will be used to generate the URL of the page and theprops
values will be passed to the page component as props.The property inside
params
must match the name of the dynamic route. Since the filename is[path].astro
, the property name passed toparams
must bepath
.In our example, the
props
object passes three properties to the page:title
: a string, representing the title of your post.body
: a string, representing the content of your entry.created
: a timestamp, based on your file creation date.
-
Use the page
props
to display your blog post. -
Navigate to your dev server preview and click on one of your posts to make sure your dynamic route is working.
Publishing your site
Section titled Publishing your siteTo deploy your website, visit our deployment guides and follow the instructions for your preferred hosting provider.