Getting Started

Upgrading StudioCMS to Latest Looking to Upgrade to the latest version? Look here!

Let’s get started

To start using StudioCMS, you’ll need:

• A version of Node.js supported by Astro^ (Bun and Deno are not supported)
• An Astro project
• A libSQL provider or self-hosted libSQL server
• The StudioCMS integration

Prepare your database

StudioCMS uses @astrojs/db to connect to your libSQL database. You can use any libSQL provider or self-hosted libSQL server.

If you are using the StudioCMS CLI, you can skip this step and use the CLI to create a new database if you have the Turso CLI installed.

For more information about the required environment variables see, Database URL and Token for @astrojs/db

Getting started with Turso

StudioCMS Coupon

Use the code STUDIOCMS10 to get 10% off for 12 months of Turso.

1. Install the Turso CLI ^

2. Login or signup ^ to Turso.

3. Create a new database.

   turso db create studiocms

4. Get and Set ASTRO_DB_REMOTE_URL

   4a. Run the show command to see information about the newly created database:

   turso db show studiocms

   4b. Copy the URL value and set it as the value for ASTRO_DB_REMOTE_URL.

   .env

   ASTRO_DB_REMOTE_URL=libsql://studiocms-yourname.turso.io

5. Get and Set ASTRO_DB_APP_TOKEN

   5a. Create a new token to authenticate requests to the database:

   turso db tokens create studiocms

   5b. Copy the output of the command and set it as the value for ASTRO_DB_APP_TOKEN.

   .env

   ASTRO_DB_APP_TOKEN=eyJhbGciOiJF...3ahJpTkKDw

You are now ready to move on to setting up your StudioCMS project!

Using another provider or self-hosted libSQL

libSQL supports both HTTP and WebSockets as the transport protocol for a remote server. It also supports using a local file or an in-memory DB.

For more information about the required environment variables see, Database URL and Token for @astrojs/db

For more information about all the potential libSQL options (including local files) see Astro Docs: Remote URL configuration options^

Creating a StudioCMS project

StudioCMS CLI

1. Creating a StudioCMS Project using the create command

   To create a new Astro project with StudioCMS using one of our pre-made templates, simply run the following command in your terminal:

   npm

   npm create studiocms@latest

   pnpm

   pnpm create studiocms@latest

   yarn

   yarn create studiocms

   After running the command, you’ll be prompted to answer a few questions about your project. Once completed, the CLI will create a new Astro project with StudioCMS in the specified directory.

   Afterward, you will be prompted to follow the next steps, which includes ensuring your environment variables are set correctly and running the project to complete the setup.

2. After running the CLI, make sure that your astro.config.mjs fle is correctly configured:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import db from '@astrojs/db';
   import node from '@astrojs/node';
   import studioCMS from 'studiocms';
   
   export default defineConfig({
       site: 'https://demo.studiocms.dev/',
       output: 'server',
       adapter: node({ mode: "standalone" }),
       integrations: [
           db(),
           studioCMS(),
       ],
   });

Astro Method

1. Creating a new Astro project

   To create a new Astro project, simply run the following command in your terminal:

   npm

   npm create astro@latest

   pnpm

   pnpm create astro@latest

   yarn

   yarn create astro

   After running the command, you’ll be prompted to answer a few questions about your project. Once completed, the CLI will create a new Astro project in the specified directory.

   You should see a “Liftoff confirmed. Explore your project!” message followed by some recommended next steps.

   cd into your new project directory to begin using Astro.

   cd my-project

   If you skipped the npm install step during the CLI wizard, then be sure to install your dependencies before continuing.

2. To add the StudioCMS integration to your project, you’ll need to install the StudioCMS package and it’s dependencies:

   npm

   npx astro add db node studiocms

   pnpm

   pnpm astro add db node studiocms

   yarn

   yarn astro add db node studiocms

3. After installing the package, make sure that your astro.config.mjs file is correctly importing and calling the integration:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import db from '@astrojs/db';
   import node from '@astrojs/node';
   import studioCMS from 'studiocms';
   
   export default defineConfig({
       site: 'https://demo.studiocms.dev/',
       output: 'server',
       adapter: node({ mode: "standalone" }),
       integrations: [
           db(),
           studioCMS(),
       ],
   });

Manual Method

1. Creating a new Astro project

   To create a new Astro project, simply run the following command in your terminal:

   npm

   npm create astro@latest

   pnpm

   pnpm create astro@latest

   yarn

   yarn create astro

   After running the command, you’ll be prompted to answer a few questions about your project. Once completed, the CLI will create a new Astro project in the specified directory.

   You should see a “Liftoff confirmed. Explore your project!” message followed by some recommended next steps.

   cd into your new project directory to begin using Astro.

   cd my-project

   If you skipped the npm install step during the CLI wizard, then be sure to install your dependencies before continuing.

2. To add the StudioCMS integration to your project, you’ll need to install the Astro StudioCMS package and it’s dependencies:

   npm

   npm i @astrojs/db @astrojs/node studiocms

   pnpm

   pnpm add @astrojs/db @astrojs/node studiocms

   yarn

   yarn add @astrojs/db @astrojs/node studiocms

3. Update your astro.config.mjs file:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import db from '@astrojs/db';
   import node from '@astrojs/node';
   import studioCMS from 'studiocms';
   
   export default defineConfig({
       site: 'https://demo.studiocms.dev/',
       output: 'server',
       adapter: node({ mode: "standalone" }),
       integrations: [
           db(),
           studioCMS(),
       ],
   });

Please note that the site option in the astro.config.mjs file is required for StudioCMS to work correctly. You can set this to your site’s URL or a placeholder URL. (i.e. https://demo.studiocms.dev/ or http://localhost:4321/)

Adapter Required

StudioCMS requires an Astro Adapter^ to work correctly. Make sure to set an adapter that supports SSR Routes in your astro.config.mjs file.

Configure StudioCMS rendering Added in beta.22

StudioCMS requires at least one of the following rendering plugins to be installed and configured within your StudioCMS project:

• @studiocms/html - for HTML rendering
• @studiocms/md - for Markdown rendering
• @studiocms/mdx - for MDX rendering
• @studiocms/markdoc - for MarkDoc rendering
• Or any other community plugin that supports rendering content in StudioCMS.

Any of these plugins can be used to render content in StudioCMS. You can use one or more of these plugins in your project, depending on your needs. They can be installed and configured using the StudioCMS config file or the Astro config file.

studiocms.config.mjs

import { defineStudioCMSConfig } from 'studiocms/config';
import html from '@studiocms/html';
import md from '@studiocms/md';

export default defineStudioCMSConfig({
    plugins: [
        html(),
        md(),
    ],
});

For more information about the available rendering plugins see, Package Catalog

Configure authentication

StudioCMS Auth requires at least the Encryption Key to be set in your .env file.

The following environment variables are required for StudioCMS authentication:

.env

# encryption key for username and password authentication
CMS_ENCRYPTION_KEY="wqR+w...sRcg=="

You can generate a secure encryption key using the following command:

openssl rand --base64 16

And set the output as the value for CMS_ENCRYPTION_KEY.

For more information about all the available authentication environment variables see, Environment variables page.

Optional: Configure oAuth authentication Revised beta.23

StudioCMS supports various oAuth authentication providers, utilizing our plugin system to enable the providers you want to use. To get started, you will need to find a plugin for the provider you want to use, or create your own plugin.

For more information about the available oAuth authentication plugins see, Package Catalog

For setting up oAuth providers, they require a callback URL. The callback URL is the path where the provider will redirect the user after authentication.

Setting up the callback URL

The callback URL should be set to one of the following paths based on your environment:

Environment	Callback URL
Production	https://your-domain.tld/studiocms_api/auth/<provider>/callback
Testing & Dev	http://localhost:4321/studiocms_api/auth/<provider>/callback

Example callback URL paths

The following paths are examples of the callback URL for each provider:

Provider	Callback PATH
GitHub	/studiocms_api/auth/github/callback
Discord	/studiocms_api/auth/discord/callback
Google	/studiocms_api/auth/google/callback
Auth0	/studiocms_api/auth/auth0/callback

Configure your package.json scripts

Setup your package.json scripts to include the --remote flag for build, and optionally for dev. (You can also run the dev command as shown in the “Running your StudioCMS Project” section)

package.json

{
    "name": "my-studiocms-project",
    "scripts": {
        "dev": "astro dev --remote",
        "build": "astro check & astro build --remote",
        "astro": "astro"
    }
}

Running your StudioCMS project

Thanks to the power of Astro running StudioCMS is as easy as running the dev command for local preview, or building and deploying to your server, for the basics of how to use it locally without building here is what you need to do.

First time Setup (or during updates if the tables schema is updated)

To start your Astro project, run the following commands in your terminal:

npm

npm run astro db push --remote

pnpm

pnpm run astro db push --remote

yarn

yarn run astro db push --remote

npm

npm run dev --remote

pnpm

pnpm run dev --remote

yarn

yarn run dev --remote

Note

The --remote flag can be removed if you have set the scripts in your package.json file to include the flag. This is explained in the “Configure your package.json scripts” section.

After running the commands, you should see a message indicating that your project is running at localhost:4321. When first setting up StudioCMS, you will prompted to finish configuring StudioCMS at http://localhost:4321/start

Running in Astro Development mode locally

To start your Astro project, run the following command in your terminal:

npm

npm run dev --remote

pnpm

pnpm run dev --remote

yarn

yarn run dev --remote

After running the command, you should see a message indicating that your project is running at localhost:4321. Open your browser and navigate to http://localhost:4321 to see your Astro project in action.

Congratulations! 🥳 You now have StudioCMS installed in your Astro project.

Adding a frontend to your StudioCMS project

StudioCMS is a headless Astro CMS, which means you have to provide your own frontend to display the content. If you are looking for a frontend that is already built, you can checkout our plugins in the Package Catalog.

Setup a blog

If you are looking to setup a blog, you can use the @studiocms/blog plugin to get started.

To install and setup the blog plugin, run the following command in your terminal:

npm

npm install @studiocms/blog

pnpm

pnpm install @studiocms/blog

yarn

yarn install @studiocms/blog

After installing the plugin, you will need to add the plugin to your studiocms.config.mjs file:

studiocms.config.mjs

import { defineStudioCMSConfig } from 'studiocms/config';
import blog from '@studiocms/blog';

export default defineStudioCMSConfig({
    dbStartPage: false,
    plugins: [
        blog(),
    ],
});

Building and deploying your StudioCMS project

After running the first time setup steps, you should build and deploy your StudioCMS project to your server.

By default, StudioCMS’s dashboard is available at http://your-domain.tld/dashboard.

This dashboard will be available for you to manage your content and settings in development mode and production mode.

It is recommended to use StudioCMS in production mode only, as the dashboard is meant to be used by the built project. (You may see some issues/errors in development mode such as a Vite dep error.)

Next steps

Check out how to set Environment Variables in StudioCMS.

Check out the Package Catalog to find and use plugins with StudioCMS.

Learn more about the StudioCMS Config options using the StudioCMS Reference pages.