# 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.

## Before you start

You need:

- Node.js 22.12 or newer.
- An account at [smoodly.io](https://smoodly.io/sign-in), 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:

```bash
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](https://smoodly.io/docs/frameworks/astro.md) 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](https://smoodly.io/docs/languages/locales.md).
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:

```bash
npx create-smoodly-app my-site --yes --framework astro --starter lorem --locales en,fi --space sp_… --secret-key sk_… --publishable-key pk_…
```

| Flag | What it answers |
| --- | --- |
| `--yes` | Takes 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\|next` | The framework. |
| `--locales en,fi` | A multilingual site. The first locale is the default. |
| `--starter lorem\|blank` | The starter. |
| `--space` | The space id, `sp_…`. |
| `--secret-key` | The space's secret key, `sk_…`. |
| `--publishable-key` | The 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:

```bash
cd my-site
```

```bash
npm run dev
```

**Astro**

Open [localhost:4321](http://localhost:4321) for the site and [localhost:4321/admin](http://localhost:4321/admin) for the admin.

**Next.js**

Open [localhost:3000](http://localhost:3000) for the site and [localhost:3000/admin](http://localhost:3000/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.

**Astro**

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

| Name | Description |
| --- | --- |
| `SMOODLY_SPACE_ID` | The space your content lives in, `sp_…`. |
| `SMOODLY_SECRET_KEY` | The server-only key the site reads content with, `sk_…`. Never expose it to the browser. |
| `SMOODLY_PUBLISHABLE_KEY` | The space's public key, `pk_…`. It reads published content and nothing else. |
| `SITE_URL` | The 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/`.

**Next.js**

The site keeps its settings in `.env.local`:

| Name | Description |
| --- | --- |
| `SMOODLY_SPACE_ID` | The space your content lives in, `sp_…`. |
| `SMOODLY_SECRET_KEY` | The server-only key the site reads content with, `sk_…`. Never expose it to the browser. |
| `SMOODLY_PUBLISHABLE_KEY` | The space's public key, `pk_…`. It reads published content and nothing else. |
| `SITE_URL` | The site's own address, `http://localhost:3000` until you deploy. Absolute links in the page head are built from it, and the push gives it to the space. |

The rest is an ordinary Next.js app. Your components live in `components/`, and the Smoodly setup lives in `smoodly/`.

[Keys](https://smoodly.io/docs/getting-started/keys.md) says what each value can reach. [Project structure](https://smoodly.io/docs/getting-started/project-structure.md) walks through every file. Next, [make your first page](https://smoodly.io/docs/getting-started/first-page.md) in the admin.
