How to deploy Astro on Saplo (fast website with islands)

Astro generates a fully static page by default - zero bytes of JavaScript at startup - and allows you to embed individual interactive components (islands) from React, Vue, or Svelte exactly where interaction is truly needed. The rest of the page remains pure HTML. The result is content pages and blogs that load instantly even on a poor connection, without compromising on a heavy framework bundle for the entire page. On Saplo, you deploy Astro like any other statically built application - the engine builds the project and exposes the ready-made dist directory under Nginx.

Who is Astro on Saplo for?

Before you start the installation, check if it's the right choice for your project:

• A blog or content website that needs to be fast - zero unnecessary JavaScript at startup, content loads instantly.
• Product documentation - content collections in Markdown and a static build are well-suited for this.
• A portfolio or landing page with a bit of interaction - a contact form or gallery as a single React or Vue island, without hydrating the entire page.
• A website that is on WordPress today only because someone needed to edit content - if editing is done via Markdown files in the repo, Astro offers the same convenience without a PHP engine and database in the background.

If the website is to be fully dynamic (different data for each query, user logins), check the Node.js stack in the app catalog instead of static Astro.

Requirements

To run Astro on Saplo, you'll need:

• A Box on any plan, S is enough to get started - the result is a static build without a memory-resident process,
• A minimum of 512 MB of free RAM for the build process itself (Astro has a heavier build toolchain than pure Vite) and 3 GB of disk space,
• A domain or subdomain *.saploapp.pl included with every plan,
• A Git repository, if you want automatic deployments (optional to start, you can also upload the application as an archive .zip through the panel).

Step-by-step installation

1. In your Saplo panel, go to App catalog and select Astro (category "Pages").
2. Specify the Box and the application name - this will create the default subdomain <name>.saploapp.pl.
3. Select the Node.js version for the build (18, 20, or 22, default is 20) and confirm the installation.
4. The engine scaffolds a minimal Astro skeleton, installs dependencies, and builds the project, then the contents of the dist directory are placed directly into the application directory, served by nginx.
5. After the installation is complete, the domain from step 2 will show the Astro starter page - from this point on, you deploy your own content to it.

Deploying your own code via Git

1. In the application details, find the Git / CI-CD section and click "Connect GitHub", confirm the installation of the "Saplo Deploy" application and point to the repository with the Astro project.
2. The saplo.yaml file must be in the root directory of the repository.
3. Commit and push the saplo.yaml file to the production branch (by default main).
4. Each subsequent git push to this branch builds the project and replaces the content of the dist directory on Box, you can see the status in the Deployments tab.
5. By default, Astro generates static files to dist/ - nginx serves it directly, without any background process on the server.

Example of a minimal saplo.yaml file for Astro:

name: my-project
stack: astro
build:
  install: npm ci
  command: npm run build
  output: dist

Astro on Saplo vs. Alternatives

FAQ

Can I write content in Markdown? Yes, content collections in Astro keep content as Markdown files in the repository, validated at build time.

Does Astro require a background process? Not in the default mode - the output is fully static and served directly by nginx, without RAM consumption after the build is complete.

When should I choose SSR (Node adapter) instead of static? When the page needs to return different data for each request (e.g., a user panel) - then in the App catalog, select the Node.js stack and configure start.command.

Can I mix islands from different frameworks on one page? Yes, Astro allows you to combine React, Vue, and Svelte components on the same page, each hydrated independently.

Will I get SSL and my own domain? Yes, the SSL certificate is automatic, and a domain or subdomain *.saploapp.pl is included with every plan.

You can set up Astro on Saplo from scratch to a working domain in a few minutes, and update content via git push without touching the admin panel or database. If the project grows to need full SSR, you'll find the Node.js stack in the same catalog.