Getting startedInstall with create-smoodly-app

Install with create-smoodly-app

One command creates a website with the Smoodly admin mounted, connected to a space that holds its content. At the end you have the Lorem Co. starter running on your machine.

View as Markdown

Before you start

You need:

  • Node.js 22.12 or newer.
  • An account at smoodly.io, with an email address.
  • A project for the site. A new project has one space, production: the content the live site reads. You build the site in it; nothing is public until you deploy.

Open the project's production space. Its page shows the three values the installer asks for: the space id (sp_…), the secret key (sk_…) and the publishable key (pk_…). Keep the page open; the next step pastes them.

Create the site

Run the installer with the folder to create:

npx create-smoodly-app my-site

It asks four things:

  1. Framework? Astro renders each section from an .astro file and caches whole pages until an editor publishes. Next.js renders sections as React server components. Both get the same admin and the same content. Frameworks has the details.
  2. Multilingual site? Answer no for one language. Yes asks for the locales, the first being the default (en, fi). You can read about this choice in Locales and routing.
  3. Starter? Lorem Co. is a small company site that uses every feature, which you then edit into your own. Blank has one of each part and nothing else: a Text section, a Button element, a posts collection with its entry page, a Home and a Page type. This guide uses Lorem Co.
  4. The space's values. Paste the space id, the secret key and the publishable key from the space page. The secret key is asked hidden. A key pasted into the wrong question is refused with a message saying which one it is.

The folder can be a name (my-site), a path (../sites/my-site) or . for the current empty folder. Its last part becomes the package name, so it takes lowercase letters, digits, dots, dashes and underscores.

Then it works on its own for a minute or two. It installs the packages and writes the space's values to an env file. It then pushes the site's content model to the space, fills the space with the starter's content and makes a first git commit.

Note
If a step fails, the folder stays and the installer prints the rest under Finish by hand: the command that picks up where it stopped. A failed push, for example, finishes with npx smoodly push && npm run seed in the new folder.

Without questions

Every question has a flag, so a script or a coding agent can run the installer with no terminal to answer in:

npx create-smoodly-app my-site --yes --framework astro --starter lorem --locales en,fi --space sp_… --secret-key sk_… --publishable-key pk_…
FlagWhat it answers
--yesTakes the default for anything not given: Astro, one language, the Lorem Co. starter. The space's values have no default, so they are still asked.
--framework astro|nextThe framework.
--locales en,fiA multilingual site. The first locale is the default.
--starter lorem|blankThe starter.
--spaceThe space id, `sp_…`.
--secret-keyThe space's secret key, `sk_…`.
--publishable-keyThe space's publishable key, `pk_…`.

npx create-smoodly-app --help prints the same list. Without a terminal and without the three values, the installer stops and names the flags to pass.

Run it

When the installer prints Ready, start the site:

cd my-site
npm run dev

Open localhost:4321 for the site and localhost:4321/admin for the admin.

The admin sends you to smoodly.io to sign in with your account, and back. The Pages list shows the Lorem Co. pages: Home, Articles (at /posts), and under the Company path About us with its Team page, and News (at /company/news).

What you got

Your content model lives in your code. The dev server and every build push it to your space, so a field you add is editable at once; nothing migrates.

The site keeps its settings in .env, Astro's own env file; the integration reads it at astro dev and astro build:

SMOODLY_SPACE_IDThe space your content lives in, `sp_…`.
SMOODLY_SECRET_KEYThe server-only key the site reads content with, `sk_…`. Never expose it to the browser.
SMOODLY_PUBLISHABLE_KEYThe space's public key, `pk_…`. It reads published content and nothing else.
SITE_URLThe site's own address, `http://localhost:4321` until you deploy. The integration makes it `site`, absolute links in the page head are built from it, and the push gives it to the space.

The rest is an ordinary Astro project. Your views live in src/, and the Smoodly setup lives in src/smoodly/.

Keys says what each value can reach. Project structure walks through every file. Next, make your first page in the admin.

Edit this page on GitHubLast updated 13 Nov 2026