Setup the SDK
To connect your app to a Satellite and use Juno's features — like authentication, data, storage, and serverless functions — you'll need to initialize the SDK.
This guide walks you through how to do that, whether you're using a plugin (Next.js, Vite) or setting things up manually.
If you intend to use Juno solely for hosting purposes, you may skip the following steps.
Initialization
- Install the Juno SDK:
- npm
- yarn
- pnpm
npm i @junobuild/core
yarn add @junobuild/core @dfinity/agent @dfinity/auth-client @dfinity/candid @dfinity/identity @dfinity/principal
pnpm add @junobuild/core @dfinity/agent @dfinity/auth-client @dfinity/candid @dfinity/identity @dfinity/principal
- Initialize your satellite in your web app:
import { initSatellite } from "@junobuild/core";
await initSatellite();
It is generally recommended to initialize globally the library at the top of your application.
Configuration
Juno uses a configuration file to determine which Satellite to connect to.
You can scaffold a minimal juno.config
file using:
npx @junobuild/cli init --minimal
This creates a juno.config
file — in TypeScript, JavaScript, or JSON depending on your preferences — at the root of your project. It contains metadata such as the Satellite ID used during SDK initialization.
If you're using Next.js or Vite, we recommend installing the official plugin. It automatically loads values from your config file and injects them into your build as environment variables.
This means you can call initSatellite()
without passing any parameters, the SDK will read them automatically from process.env
or import.meta.env
.
import { withJuno } from "@junobuild/nextjs-plugin";
// withJuno wraps your Next.js config and injects values from juno.config
export default withJuno();
import juno from "@junobuild/vite-plugin";
// Automatically injects values from juno.config for the build
export default defineConfig({
plugins: [juno()]
});
The templates already include both the config file and the plugin setup.
Not using a plugin?
You can also pass the Satellite ID manually to the SDK, though using the plugins is the preferred approach:
import { initSatellite } from "@junobuild/core";
await initSatellite({
satelliteId: "your-actual-satellite-id"
});