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 database connection (libSQL, MySQL, or PostgreSQL)
• The StudioCMS integration

Prepare your database

Turso (libSQL)

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 CMS_LIBSQL_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 CMS_LIBSQL_URL.

   .env

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

5. Get and Set CMS_LIBSQL_AUTH_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 CMS_LIBSQL_AUTH_TOKEN.

   .env

   CMS_LIBSQL_AUTH_TOKEN=eyJhbGciOiJF...3ahJpTkKDw

libSQL

Make sure you have a libSQL database setup and running. You can use a local installation, a Docker container, or a managed database service such as Turso^.

.env

CMS_LIBSQL_URL=libsql://your-database.turso.io
CMS_LIBSQL_AUTH_TOKEN=<your-auth-token> (optional)

For more information about the required environment variables see, Required environment variables for libSQL

MySQL

Make sure you have a MySQL database setup and running. You can use a local installation, a Docker container, or a managed database service.

.env

CMS_MYSQL_DATABASE=<your-database-name>
CMS_MYSQL_USER=<your-database-user>
CMS_MYSQL_PASSWORD=<your-database-password>
CMS_MYSQL_HOST=<your-database-host>
CMS_MYSQL_PORT=<your-database-port>

For more information about the required environment variables see, Required environment variables for MySQL

PostgreSQL

Make sure you have a PostgreSQL database setup and running. You can use a local installation, a Docker container, or a managed database service.

.env

CMS_PG_DATABASE=<your-database-name>
CMS_PG_USER=<your-database-user>
CMS_PG_PASSWORD=<your-database-password>
CMS_PG_HOST=<your-database-host>
CMS_PG_PORT=<your-database-port>

For more information about the required environment variables see, Required environment variables for PostgreSQL

You are now ready to move on to creating your StudioCMS project!

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 node from '@astrojs/node';
   import studioCMS from 'studiocms';
   
   export default defineConfig({
       site: 'https://demo.studiocms.dev/',
       output: 'server',
       adapter: node({ mode: "standalone" }),
       integrations: [
           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 node studiocms

   pnpm

   pnpm astro add node studiocms

   yarn

   yarn astro add 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 node from '@astrojs/node';
   import studioCMS from 'studiocms';
   
   export default defineConfig({
       site: 'https://demo.studiocms.dev/',
       output: 'server',
       adapter: node({ mode: "standalone" }),
       integrations: [
           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/node studiocms

   pnpm

   pnpm add @astrojs/node studiocms

   yarn

   yarn add @astrojs/node studiocms

3. Update your astro.config.mjs file:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import node from '@astrojs/node';
   import studioCMS from 'studiocms';
   
   export default defineConfig({
       site: 'https://demo.studiocms.dev/',
       output: 'server',
       adapter: node({ mode: "standalone" }),
       integrations: [
           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 Database dialect Added in beta.31

If you are using a database other than libSQL you will need to configure the db option in your studiocms.config.mjs file to specify the correct dialect.

studiocms.config.mjs

export default defineStudioCMSConfig({
  db: {
    dialect: 'postgres', // 'libsql' | 'postgres' | 'mysql'
  },
})

Ensure database client packages are installed

You will also need to install the necessary database client packages for your chosen database dialect:

libSQL (default)

npm

npm i @libsql/client kysely-turso

pnpm

pnpm add @libsql/client kysely-turso

yarn

yarn add @libsql/client kysely-turso

MySQL

npm

npm i mysql2

pnpm

pnpm add mysql2

yarn

yarn add mysql2

PostgreSQL

npm

npm i pg

pnpm

pnpm add pg

yarn

yarn add pg

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
• @studiocms/wysiwyg - for WYSIWYG 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.

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’s built-in authentication 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 Storage API Manager (optional) Added in v0.1.0

StudioCMS supports using different Storage API Managers to handle file and image storage. By default, StudioCMS uses a built-in no-op storage manager that does not store any files or images.

To configure a different Storage API Manager, you will need to install the appropriate plugin and configure it in your studiocms.config.mjs file.

For more information about the Storage API see, Storage API Docs

For available storage manager plugins, see the Package catalog.

Example: Configure S3 Storage Manager

1. Install the @studiocms/s3-storage plugin:

   npm

   npm i @studiocms/s3-storage

   pnpm

   pnpm add @studiocms/s3-storage

   yarn

   yarn add @studiocms/s3-storage

2. Update your studiocms.config.mjs file to use the S3 Storage Manager:

   studiocms.config.mjs

   import { defineStudioCMSConfig } from 'studiocms/config';
   import s3Storage from '@studiocms/s3-storage';
   
   export default defineStudioCMSConfig({
      storageManager: s3Storage(),
   });

3. Set the required environment variables for the S3 Storage Manager in your .env file:

   Supported S3 Providers

   StudioCMS’s S3 Storage Manager is built using the @aws-sdk/client-s3 package, which supports any S3-compatible storage provider, including AWS S3, DigitalOcean Spaces, MinIO, and others.

   .env

   CMS_S3_PROVIDER=ExampleS3Provider
   CMS_S3_ACCESS_KEY_ID=<your-access-key-id>
   CMS_S3_SECRET_ACCESS_KEY=<your-secret-access-key>
   CMS_S3_BUCKET_NAME=<your-bucket-name>
   # CMS_S3_ENDPOINT= # Optional: Specify a custom endpoint if required by your provider
   # CMS_S3_REGION= # Optional: Specify the region if required by your provider
   # CMS_S3_FORCE_PATH_STYLE= # Optional: Use path-style URLs for S3 objects
   # CMS_S3_PUBLIC_ENDPOINT= # Optional: Custom public endpoint for accessing files

   For more information about the Environment variables with the S3 Storage Manager see, S3 Storage: Environment Variables

Configure your package.json scripts

Setup your package.json scripts to include the following StudioCMS commands for easier use:

package.json

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

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 studiocms migrate --latest

pnpm

pnpm run studiocms migrate --latest

yarn

yarn run studiocms migrate --latest

npm

npm run dev

pnpm

pnpm run dev

yarn

yarn run dev

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

pnpm

pnpm run dev

yarn

yarn run dev

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.

You can access the StudioCMS dashboard at http://localhost:4321/dashboard by default to manage your content and settings.

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

For example if you want to build a blog using StudioCMS, you can use the @studiocms/blog plugin to get started quickly without having to build everything from scratch. This plugin provides a simple blog frontend that removes the need to have any source files for your frontend pages.

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 a custom frontend

If you want to build a custom frontend for your StudioCMS project, you can use the StudioCMS SDK or StudioCMS RestAPI to fetch and a StudioCMS Rendering plugin to render content from StudioCMS on your custom pages.

If you want to build a custom frontend for your StudioCMS project, you can use the StudioCMS Renderer component and SDK to render the content from StudioCMS on your custom pages.

See the Custom Frontend Guides for more guides and tutorials on building a custom frontend with StudioCMS.

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.