Skip to content
Malouf Developer Docs

Getting Started with Astro

The template project is divided into 2 folders: Astro (frontend) and Strapi (backend/api). You will need to run these two projects in separate terminals. Strapi will always need to be running if you are fetching API requests. Please read their respective README in github for detailed instructions.

The project is currently using node version 20.12

Quick Astro/Strapi Project Setup Guide

  1. Go to the astrapier-plate repo on our GitHub, which can be accessed here. Click on the green button that says “Use this template” then click “Create a new repository”.
  2. Enter the name of your repo and if you want, enter a description, then click “Create repository”. You shouldn’t have to modify any of the other settings on this page.
  3. After you created your new repo, clone the files onto your computer, and open in VSCode.
  4. Open two terminals, one will be for Astro and the other for Strapi. In one of them, run cd astro and then npm install. In the second, run cd strapi and then yarn install.
  5. While this is running, open your web browser and access our Box account where we store all of our super secret super soldier serums (SSSSS for short 🐍)
  6. Click on the Malouf folder > Strapi & Astro > new site setup envs. You will need the information from the “strapi_env.txt” and “astro_env.txt” files.
  7. Head back to VSCode. In the file explorer on the left hand side, open the strapi folder and you will see a file called “.env.example”. Rename this file so that it just says “.env” and then open it up. Go back to your web browser and to the Box page you had open. Copy and paste everything from the strapi_env file and paste that into the .env file in VSCode, replacing whatever was exisiting prior. You will see a bunch of variables (which are all uppercase) followed by an equal (=) sign. You will need to put everything after that in quotes so is becomes a string. Example: HOST='0.0.0.0'. You shouldn’t have to change any of the variable values except for the one called DO_SPACE_DIRECTORY. Its currently set to “site_name_here!!!!” and you will just need to replace that with the name of the site you are working on.
  8. Do the same for the .env file in the astro folder, but using the info in the astro_env doc in Box. There isnt a .env file that exists already in VSCode like the strapi one, so you will just need to make a new one. Copy and paste, thats it.
  9. Next, in your web browser, open up Digital Ocean and click on “Databases” in the navigation bar to the left. Its under the “MANAGE” section. You will see 3 databases (or at least at the time of writing this) but you will want to click on the one that is called “db-postgresql-sfo3-strapi”. Then navigate to the “Users & Databases” tab where you will create a new database. (Databases within Databases… Dataception). At the bottom of the databases section, you will type in the name of your new one, and them click save. NOTE that the name should be the name of the website and the same as the name you used for the variable DO_SPACE_DIRECTORY.
  10. After you have done this, scroll back to the top and click on the tab that says “Connection Pools” and click “Create a Connection Pool”. The “Pool Name” needs to be the same as the database name. Under the “Select Database” section, click on the new database you just created (if you don’t see it, try refreshing the page). The other settings like “Select User” should be strapi, the “Pool Mode” should be transaction and the “Pool size” of 3. Then click “Create Pool”.
  11. Now open up your database tool like DBeaver or TablePlus and create a new connection. You will want to use the connection details for the defaultdb with a user of doadmin. These can be found in the overview tab for the db-postgresql-sfo3-strapi within Digital Ocean.
  12. Open up the new database you created within your database tool, and type/run the following in the SQL Command Terminal GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public to strapi or GRANT ALL ON SCHEMA public to strapi.

GREAT JOB SO FAR!! We are almost done, hang in there!

  1. Go back to VSCode and open up the database.js file which is located at /strapi/config/database.js. You will need to update the config to point to the new connection pool you created, as it is currently pointing to the default database. Update the following section and only change the “connection_pool_name” string:
database: env('DATABASE_NAME', 'connection_pool_name'),
  1. Now that the configuration is set up, you should be good to go! In the terminal you have open for strapi, type yarn develop and in the astro terminal, first run nvm use 20.12 and then npm run dev. IT IS VERY IMPORTANT THAT YOU USE NODE VERSION 20.13 OTHERWISE EVERYTHING WILL EXPLODE AND NOT WORK. Then go to localhost:4321 in your browser and start working your magic!

Please note: A lot of this information can be found in different places in our dev docs or in README files of the projects. The goal was to condense this in one place and make it easy for you to get up and running. If you have any questions or you are running into errors getting it up and running, even after following these steps, reach out to your team or look at some of the more in depth info in the docs.

Happy Coding!

.env Variables

You will need an env with several values from the Strapi part of the project. This env will live in the root of the Strapi folder as well. Please reach out to a team member to get access to the env.

Once you have an ENV set up, you will need to change a few values. Specifically those relating to Digital Ocean Spaces where we are hosting images for Strapi. These variables start with DO.. for reference. You will need to change the variable DO_SPACE_DIRECTORY to the site name. Examples would be bloomington or droz. This will create a folder within the Digital Ocean spaces specifically for those images.

Any variables used within the Astro product will need to have a new env at the root of the astro project. Astro runs on VITE so you will need to use import.meta.env.VARIABLE_NAME when you call them within your project. You are read more about setting up Astro environment variables here.

Digital Ocean

We are currently using Digital Ocean for our database as well as image hosting. To add a new site to the database, please following these steps:

  1. Login to Digital Ocean and access the Database tab in the far left menu
  2. Select the database db-postgresql-sfo3-strapi
  3. Within the database, go into Users & Databases. Add a new database with the site name at the bottom of the screen. Please avoid using spaces.
  4. Within the database, go into Connection Pools. Create a new connection pool for that database with the user Strapi. The other settings should be transactional with a pool size of 3. Keep the pool name the same as the database name.
  5. Before you can access the database locally, you will need to adjust the user permissions. This can be done in a database tool like DBeaver or TablePlus. You will want to use the connection details for the defaultdb with a user of doadmin. These can be found in the overview tab for the db-postgresql-sfo3-strapi within Digital Ocean.
  6. Within the database table you created for the new site, run GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public to strapi or GRANT ALL ON SCHEMA public to strapi

Config Updates

The config will be pointing to the default database, which you will need to update with the new connection pool you created. If you have not created one on Digital Ocean (where the database is hosted), you will need to reach out to Phil, Austin, Aaron, or Robert to have an account made. Once the connection pool is live, update /strapi/config/database.js with a new database value.

database: env('DATABASE_NAME', 'connection_pool_name'),

Important Details

To make development and content updates easier, here are some patterns and plugins to be aware of in this project.

Strapi REST API

We are using the REST API to fetch content-types via API endpoints. When you create a new collection or single type, it becomes accessible through the API. All the of the fetches are done in the Astro frontmatter.

Nested Content

Due to the Strapi response structure, you will sometimes get nested content. This is particularly true if you are using relations. The template uses relations for adding variants to products. If you run into issues not being able to access nested objects like images, you can take either of these approaches:

  1. Narrow down your fetch to target a specific id
const {id} = Astro.props;
const response = await fetch(`http://localhost:1337/api/variants/${id}?populate=*`)
.then(res => res.json());
  1. Use the strapi deep plugin (pre-installed in the the template) to populate deeply nested structures.
const response = await fetch('http://localhost:1337/api/home?populate=deep')
.then(res => res.json())

Type Compatibility

Astro uses Typescript, which has some more strict guidelines than Javascript and will throw build errors. One issue you might run into while working with objects is the type compatibility. In order to type objects and variables properly in Astro, you can use a types.ts file where you will pre-define your relating types and import as necessary. When in doubt you can use type any.

export interface Page {
  attributes: {
    name: string,
    meta_title: string,
    meta_description: string,
    content: any
  }
}
pages.map(({id}: Page) => (
  <PageContent id={id} />
))

Astro Conditional Statements

Astro uses HTML and a JSX-like template language. Most JSX expressions will work by default. You can read more about Astro syntax here. For if/else statements outside of the frontmatter or script tag, we are using the syntax below:

{!variants && (
  <p>{size}</p>
  <p>{`$${msrp}`}</p>
)}

{variants && (
  variants.map(({id}: any) => (
    <VariantData id={id} />
  ))
)}

Tree Shaking with Tailwind

By default Tailwind will “tree shake”, or in other words only complie with the styles are being actively used in the base Astro project. However, you might run into issues if you are using the rich text field in Strapi to input HTML. To have Tailwind render styles that aren’t in the Astro build, you can Safelist them in the tailwind config.

Partytown

Partytown is a lazy-load library that keeps third-party scripts from killing your overall site performance. You can find out more about including it in Astro here.