Skip to main content

Use Juno with Astro

Easily set up and deploy your Astro project with Juno.

What would you like to do?

Options

Choose Build if you want to build a full featured rich application.

Choose Hosting if you just want to deploy a website.

Build​

This guide provides quickstart instructions for integrating Juno and building a feature-rich application. It also includes guidance on developing locally.

1. Choose Your Integration Path​

You can either start a new project or add Juno to an existing app.

Path A: Start a new project with a template​

Create a new project using the Juno quickstart CLI:

npm create juno@latest -- --template astro-starter

Path B: Integrate Juno into an existing Astro app​

Navigate to your existing app:

cd your-existing-app

and install Juno SDK:

npm i @junobuild/core

2. Start the Emulator​

If the Juno admin CLI (required to run the emulator) is not installed yet, run:

npm i -g @junobuild/cli

Once installed, start the local emulator:

juno dev start

Open the Console UI at http://localhost:5866/.

note

When developing locally, you get an all-in-one emulator that closely mimics the production environment. This includes providing Juno and its Console UI locally.

Sign in, create a Satellite, navigate to the Datastore section, and create a collection named demo.

3. Configure​

To initialize the library with the Satellite ID you created, configure it in the juno.config.mjs file (or other extension), which should be available at the root of your project.

Replace <DEV_SATELLITE_ID> with the ID.

import { defineConfig } from "@junobuild/config";

/** @type {import('@junobuild/config').JunoConfig} */
export default defineConfig({
  satellite: {
    ids: {
      development: "<DEV_SATELLITE_ID>",
      production: "<PROD_SATELLITE_ID>"
    },
    source: "out",
    predeploy: ["npm run build"]
  }
});

4. Install the Plugin​

You'll need to install the plugin to automatically inject the Satellite ID into your app as an environment variable.

Proceed as documented here.

astro.config.mjs
import { defineConfig } from "astro/config";
import juno from "@junobuild/vite-plugin";
import sitemap from "@astrojs/sitemap";

// https://astro.build/config
export default defineConfig({
  site: "https://hello.com",
  integrations: [sitemap()],
  vite: {
    plugins: [juno()]
  },
  devToolbar: {
    enabled: false
  }
});

5. Insert data from your app​

In index.astro, initialize the Satellite.

Add an insert function to persist a document.

index.astro
<!doctype html>
<html lang="en">
  <body>
    <main>
      <button id="insert">Insert a document</button>
      <p>Document persisted key: <output id="result"></output></p>

      <script>
        import { initSatellite, setDoc } from "@junobuild/core";

        // Initialize Juno's satellite
        document.addEventListener("DOMContentLoaded", initSatellite, {
          once: true
        });

        // Insert a document in Juno's datastore
        const insert = async () => {
          const doc = await setDoc({
            collection: "demo",
            doc: {
              key: window.crypto.randomUUID(),
              data: {
                hello: "world"
              }
            }
          });

          const result = document.querySelector("#result");
          if (result !== null) {
            result.textContent = doc.key;
          }
        };

        document
          .querySelector("#insert")
          ?.addEventListener("click", insert, { passive: true });
      </script>
    </main>
  </body>
</html>

6. Start the app​

Start the app, go to http://localhost:4321/ in a browser, click "Insert a document", and you should see the data successfully persisted in your satellite on the blockchain.

What's Next: Going Live

Once you're ready to deploy your app for others to access, continue to the Deployment guide.

Hosting​

If you already have an Astro app, you're all set — proceed to the Deployment section to upload your project to production.

Otherwise, you can bootstrap a new website using the Juno template by running the following command:

npm create juno@latest -- --template astro-starter

Once you’re set up, continue to the Deployment section below.

Deployment​

Use this guide to deploy your project to production — directly to a smart contract on mainnet.

1. Set up a satellite​

If you haven't created a satellite yet, go ahead and create a new one in the Juno's console.

2. Deploy​

Once your satellite is up and running, you can proceed with uploading your app to your smart contract.

You can either automate your deployment with GitHub Actions (recommended) or deploy manually from your device. Choose your method: