Astro - An introduction to your next project

That we are enthusiastic about Astro and its features is known at least since our Colophon. As a static page generator (SSG), Astro makes our content available to our visitors via the integrated Collections feature, and its ease of use allows us to focus on our content.

In this article we will show you - as announced - how to set up and publish your own project with Astro.

This article assumes a certain level of knowledge in the areas of HTML, CSS and JavaScript and is therefore not necessarily suitable for beginners.

Installation

Before we start the installation, we need Node.js 20 or higher and the code editor of your choice. Once these requirements are met, you have a choice of two installation paths:

• Our own Astro Boilerplate with out-of-the-box support for TypeScript, TailwindCSS and many more features, or…

• … a manual installation via the Astro Setup Wizard.

For this article, we will use our boilerplate, whose features we will discuss in more detail below.

Astro Boilerplate

You have decided in favor of our boilerplate? Great. Click the button below to download and unzip the project.

You prefer an installation according to your wishes? Then follow the manual installation.

Manual installation

If you have already downloaded the boilerplate, skip this step.

Run the following create command in the terminal to start Astro’s handy setup wizard and begin configuring your project:

npm create astro@latest

Installation of required packages

If you chose to use boilerplate or skipped the installation step for npm in the setup wizard, you will need to install the required packages in the project directory before proceeding:

npm install

Launch Astro

To start Astro, execute the following dev command in the project directory:

npm run dev

Under the URL displayed in the terminal - typically http://localhost:4321/ - you will find your new website. On our boilerplate, you will be greeted by the following welcome page:

If you have chosen the manual installation step, the initial appearance of the home page will depend on the template you have chosen.

The following sections refer exclusively to the boilerplate we provide. If you chose to install manually, the excellent Documentation of Astro is available, or you can jump directly to the Deployment section if you are already familiar with Astro.

Configuration

Our boilerplate offers several configuration options by default and already provides some preconfigured options for the following tools.

Astro

astro.config.ts is preconfigured with support for MDX and TailwindCSS.

export default defineConfig({
  srcDir: ".",
  integrations: [
    mdx(),
    tailwind({
      applyBaseStyles: false,
    }),
  ],
});

More integrations and frameworks can be added via astro add. More about this in the section Interactivity.

Alpine.js

For basic interactivity, Alpine.js is installed and follows our configuration presented earlier in the article Temporary and Persistent State Management with Alpine.js.

export const app = () => ({
  // ...

  // init() {
  //   console.log('Hello World')
  // }
});

app is imported into the file scripts/globals.ts, initiated and globally included via the <root> layout.

TailwindCSS

Styles can be defined with two tools: TailwindCSS and SCSS.

tailwind.config.ts uses the theming of shadcn/ui and a preconfigured theme for @tailwindcss/typography.

The CSS variables of the styles are defined in the file styles/globals.scss and provide a preset for dark or light mode via the CSS media query prefers-color-scheme.

Pages, Components and Layouts

We already provide the pages/index.astro page. It uses the <Root> layout and contains the <Welcome /> component.

Pages

pages/index.astro` is your start page and contains besides the welcome page only the layout of your future page.

With the constant meta you can manage the metadata of the corresponding page and pass this information to the layout <root>. The following metadata is available:

interface Props {
  meta: {
    title?: string;
    description?: string;
    image?: {
      src: string;
      alt?: string;
    };
  };
}

Components

The boilerplate comes with some handy components to get you started:

• <Footer /> - *Empty component for binding your own footer.

• <Meta> - Represents common metadata. Allows expansion with <slot />.

• <Navigation> - Empty component for binding custom navigation.

• <Welcome /> - Example component reflecting the changes made to the project.

Layouts

The <Root> layout is essential for any page and also includes Alpine.js and the <Navigation /> and <Footer /> components.

In addition, the layout contains the <Meta> component, which receives our metadata defined in the pages. This component also contains the default title of the page.

Interactivity

As already introduced in the Configuration section, our boilerplate uses Alpine.js for a basic level of interactivity.

For more sophisticated applications, we recommend the solutions integrated by Astro for various frameworks such as React, Vue or Svelte.

Frontend Frameworks

Based on our configuration, the following two frameworks and components are particularly suited for use in our boilerplate:

• Pines - a UI library based on Alpine and Tailwind.
• shadcn/ui -a UI library based on React, Radix and Tailwind.

When using shadcn/ui, follow Astro’s rules for hydrating components.

Deployment

Wenn du deine eigene Seite erstellt hast, musst du sie nur noch veröffentlichen. Am einfachsten geht das mit einer statisch generierten Seite.

Grundsätzlich bist du an keinen Hosting-Provider gebunden und hast die Wahl, wie du deine Seite veröffentlichen möchtest.

Local

Many providers offer services for the deployment of your site. However, you can also compile your page locally. For this you use the common build command:

npm run build

By default you will find your compiled page in the directory dist/. Now you just have to upload your page to your provider and your first project is online.

Services

Astro supports many providers out of the box and without further configuration. Prominent examples are Cloudflare and Vercel, which explain and execute the deployment process in a simple dialog.

In addition to static page generation, many providers also support Server-side Rendering (SSR) for Astro. According to Astro’s own documentation, SSR provides access to the following features:

• Implement sessions for login state in your app.
• Render data from an API called dynamically with fetch.
• Deploy your site to a host using an adapter.

For simple and manageable projects that do not rely on external resources, it is recommended to use SSG. If the project is more sophisticated, it is advisable to look into SSR to integrate the required resources as you see fit.

TL;DR

Astro in combination with our boilerplate gives you the tools and flexibility to approach your next project the way you want. From setup to deployment, we’ll walk you through it in this article.