Install Smootify in Astro by hand

Smootify for Astro is an Astro integration. It adds Smootify’s script to every page, reads your Shopify catalog into content collections, and writes the first load of each page into the HTML at build time. This page adds it to a project, explains each option and checks that it runs.

1. Add the package

Add the integration with Astro’s own command. It installs @smootify/astro from npm and adds smootify() to astro.config.mjs:

npx astro add @smootify/astro

In a project that uses pnpm, run pnpm astro add @smootify/astro instead: the lockfile decides the package manager, never mix two. If the project has no Cloudflare adapter yet, add it the same way: npx astro add cloudflare.

2. Add the integration to astro.config

This is the config Studio writes for a project on Cloudflare:

// astro.config.mjs
import { defineConfig } from "astro/config";
import smootify from "@smootify/astro";
import cloudflare from "@astrojs/cloudflare";

export default defineConfig({
  site: "https://shop.example.com",
  output: "static",
  trailingSlash: "always",
  adapter: cloudflare(),
  integrations: [smootify({ siteId: "<24-character Smootify site id>" })],
});

What each line does:

• site is the address the site is served from. Canonical links, og:url and the JSON-LD need it. Until the site has a domain, use http://localhost:4321.
• output: "static" builds every page ahead. Pages that read live data opt out of it one by one: see Content from Shopify.
• trailingSlash: "always" makes every page address end with /. The static host answers /products/shirt/ and redirects /products/shirt, so links, canonical addresses and the sitemap must all use the address that answers. Smootify reads this setting and writes its own links with the slash.
• adapter is @astrojs/cloudflare. Smootify’s hosting is Cloudflare: see Deploy to Cloudflare.
• smootify({ siteId }) is the integration.

3. Set the site id

siteId is the 24-character id of your site in Smootify. The integration reads the store and the public Storefront token from it, at build time. The token is never written into your pages.

Instead of the option, you can set the SMOOTIFY_SITE_ID environment variable. In a project made by Studio, the id sits in one file, smootify.config.mjs, which the config and the content collections both read.

4. Options

smootify() takes these options. Only siteId is required.

For the locales and webhook options, the details are in the pages that use them. Smootify’s own options, such as the URLs of your product pages, go in userOptions:

smootify({
  siteId: "<24-character Smootify site id>",
  userOptions: { productsBase: "shop", collectionsBase: "categories", vendorsBase: "brands" },
});

Smootify writes them before its script, and the build uses them too: the links and prices drawn at build time, and the sitemap’s on-demand pages, follow the same options. Put every option the page depends on here, not in a script of your own. The default routes are plural: /products/<handle>, /collections/<handle> and /vendors/<handle>. If you use other names, name the page folders the same way and set the three bases here.

With trailingSlash: "always", Smootify sets its own trailingSlash option to true. Your own value in userOptions wins.

5. Plans and domains

The plans are the same as for every Smootify site:

• Free works on localhost and on *.workers.dev addresses, and shows the Smootify badge.
• Lite is the production licence: your registered domain needs it. It includes every client element.
• Server adds the server add-ons, on the licensed domain.

Add the domain of the site in the Smootify dashboard before you go live on it.

6. Check that it runs

1. Run pnpm dev. The site runs at http://localhost:4321.
2. Open a page, then the browser’s Network panel. The page loads loader.js from cdn.smootify.io.
3. Run pnpm build. The log has a line that starts with seed:, with the number of pages seeded.

If the build ends with an error that names siteId, the id is missing or is not 24 characters of lower-case hexadecimal.

Before you publish