Skip to content
StudioCMS Docs
Main Site

Getting Started

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

Let’s get started

Section titled “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

Section titled “Prepare your database”

  1. Install the Turso CLI ^

  2. Login or signup ^ to Turso.

  3. Create a new database.

    Terminal window
    turso db create studiocms

  4. Get and Set CMS_LIBSQL_URL

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

    Terminal window
    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:

    Terminal window
    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

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

Creating a StudioCMS project

Section titled “Creating a StudioCMS project”

  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:

    Terminal window
    npm create studiocms@latest

    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(),
        ],
    });

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/)

Configure StudioCMS Database dialect Added in beta.31

Section titled “Configure StudioCMS Database dialect ”

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 
function defineStudioCMSConfig(config: StudioCMSOptions): StudioCMSOptions
A utility function to define the StudioCMS config object.
This function is used to define the optional StudioCMS
config object in the Astro project root. The expected file
name is studiocms.config.mjs. And it should be adjacent
to the Astro project's astro.config.mjs file.


StudioCMS will attempt to import this file and use the default
export as the StudioCMS config object automatically if it exists.


Using this function is optional, but it can be useful for IDEs
to provide better intellisense and type checking.
@example 
// studiocms.config.mjs
import { defineStudioCMSConfig } from 'studiocms/config';


export default defineStudioCMSConfig({
 dbStartPage: true,
 // ...Other Options
})
defineStudioCMSConfig({
  
StudioCMSOptions.db?: DBConfigSchema
Database Configuration
db: {
    
DBConfigSchema.dialect?: "postgres" | "libsql" | "mysql"
Database Dialect to use
@default ― 'libsql'
dialect: 'postgres', // 'libsql' | 'postgres' | 'mysql'
  },
})

Ensure database client packages are installed

Section titled “Ensure database client packages are installed”

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

Terminal window
npm i @libsql/client @libsql/kysely-libsql

Configure StudioCMS rendering Added in beta.22

Section titled “Configure StudioCMS rendering ”

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

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 { 
function defineStudioCMSConfig(config: StudioCMSOptions): StudioCMSOptions
A utility function to define the StudioCMS config object.
This function is used to define the optional StudioCMS
config object in the Astro project root. The expected file
name is studiocms.config.mjs. And it should be adjacent
to the Astro project's astro.config.mjs file.


StudioCMS will attempt to import this file and use the default
export as the StudioCMS config object automatically if it exists.


Using this function is optional, but it can be useful for IDEs
to provide better intellisense and type checking.
@example 
// studiocms.config.mjs
import { defineStudioCMSConfig } from 'studiocms/config';


export default defineStudioCMSConfig({
 dbStartPage: true,
 // ...Other Options
})
defineStudioCMSConfig } from 'studiocms/config';
import 
function html(options?: HTMLSchemaOptions): StudioCMSPlugin
Creates the StudioCMS HTML plugin.


This plugin integrates HTML page type support into StudioCMS, providing editor and renderer components.
It resolves configuration options, sets up Astro integrations, and registers the HTML page type for rendering.
@param ― options - Optional configuration for the HTML schema.
@returns ― The StudioCMS plugin configuration object.
html from '@studiocms/html';
import 
function md(options?: MarkdownSchemaOptions): StudioCMSPlugin
Creates a StudioCMS plugin for Markdown page types.


This plugin configures StudioCMS to support Markdown content, including rendering and editing components,
integration with Astro, and optional callout themes. It resolves user-provided options, sets up virtual imports,
and injects necessary styles and scripts for Markdown rendering.
@param ― options - Optional configuration for Markdown schema and rendering behavior.
@returns ― A StudioCMSPlugin instance configured for Markdown support.
@example 
import { studiocmsMD } from '@studiocms/md';
const plugin = studiocmsMD({ flavor: 'studiocms', callouts: 'obsidian' });
md from '@studiocms/md';


export default 
function defineStudioCMSConfig(config: StudioCMSOptions): StudioCMSOptions
A utility function to define the StudioCMS config object.
This function is used to define the optional StudioCMS
config object in the Astro project root. The expected file
name is studiocms.config.mjs. And it should be adjacent
to the Astro project's astro.config.mjs file.


StudioCMS will attempt to import this file and use the default
export as the StudioCMS config object automatically if it exists.


Using this function is optional, but it can be useful for IDEs
to provide better intellisense and type checking.
@example 
// studiocms.config.mjs
import { defineStudioCMSConfig } from 'studiocms/config';


export default defineStudioCMSConfig({
 dbStartPage: true,
 // ...Other Options
})
defineStudioCMSConfig({
    
StudioCMSOptions.plugins?: StudioCMSPlugin[]
Add Plugins to the StudioCMS
plugins: [
        
function html(options?: HTMLSchemaOptions): StudioCMSPlugin
Creates the StudioCMS HTML plugin.


This plugin integrates HTML page type support into StudioCMS, providing editor and renderer components.
It resolves configuration options, sets up Astro integrations, and registers the HTML page type for rendering.
@param ― options - Optional configuration for the HTML schema.
@returns ― The StudioCMS plugin configuration object.
html(),
        
function md(options?: MarkdownSchemaOptions): StudioCMSPlugin
Creates a StudioCMS plugin for Markdown page types.


This plugin configures StudioCMS to support Markdown content, including rendering and editing components,
integration with Astro, and optional callout themes. It resolves user-provided options, sets up virtual imports,
and injects necessary styles and scripts for Markdown rendering.
@param ― options - Optional configuration for Markdown schema and rendering behavior.
@returns ― A StudioCMSPlugin instance configured for Markdown support.
@example 
import { studiocmsMD } from '@studiocms/md';
const plugin = studiocmsMD({ flavor: 'studiocms', callouts: 'obsidian' });
md(),
    ],
});
For more information about the available rendering plugins see, Package Catalog

Configure authentication

Section titled “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:

Terminal window
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

Section titled “Optional: Configure oAuth authentication ”

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
Section titled “Setting up the callback URL”

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

EnvironmentCallback URL
Productionhttps://your-domain.tld/studiocms_api/auth/<provider>/callback
Testing & Devhttp://localhost:4321/studiocms_api/auth/<provider>/callback
Example callback URL paths
Section titled “Example callback URL paths”

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

ProviderCallback 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

Section titled “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

Section titled “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)

Section titled “First time Setup (or during updates if the tables schema is updated)”

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

Terminal window
npm run studiocms migrate --latest
Terminal window
npm 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

Section titled “Running in Astro Development mode locally”

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

Terminal window
npm 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

Section titled “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

Section titled “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:

Terminal window
npm install @studiocms/blog

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

studiocms.config.mjs
import { 
function defineStudioCMSConfig(config: StudioCMSOptions): StudioCMSOptions
A utility function to define the StudioCMS config object.
This function is used to define the optional StudioCMS
config object in the Astro project root. The expected file
name is studiocms.config.mjs. And it should be adjacent
to the Astro project's astro.config.mjs file.


StudioCMS will attempt to import this file and use the default
export as the StudioCMS config object automatically if it exists.


Using this function is optional, but it can be useful for IDEs
to provide better intellisense and type checking.
@example 
// studiocms.config.mjs
import { defineStudioCMSConfig } from 'studiocms/config';


export default defineStudioCMSConfig({
 dbStartPage: true,
 // ...Other Options
})
defineStudioCMSConfig } from 'studiocms/config';
import 
function blog(options?: StudioCMSBlogOptions): StudioCMSPlugin
Creates and configures the StudioCMS Blog plugin.
@param ― options - Optional configuration options for the blog plugin.
@returns ― The configured StudioCMS plugin.
@example 
const blogPlugin = studioCMSBlogPlugin({
  blog: {
    title: 'My Blog',
    enableRSS: true,
    route: '/my-blog'
  },
  sitemap: true,
  injectRoutes: true
});
@param ― options.blog - Blog-specific options.
@param ― options.blog.title - The title of the blog. Defaults to 'Blog'.
@param ― options.blog.enableRSS - Whether to enable RSS feed. Defaults to true.
@param ― options.blog.route - The route for the blog. Defaults to '/blog'.
@param ― options.sitemap - Whether to trigger sitemap generation. Defaults to true.
@param ― options.injectRoutes - Whether to inject routes for the blog. Defaults to true.
blog from '@studiocms/blog';


export default 
function defineStudioCMSConfig(config: StudioCMSOptions): StudioCMSOptions
A utility function to define the StudioCMS config object.
This function is used to define the optional StudioCMS
config object in the Astro project root. The expected file
name is studiocms.config.mjs. And it should be adjacent
to the Astro project's astro.config.mjs file.


StudioCMS will attempt to import this file and use the default
export as the StudioCMS config object automatically if it exists.


Using this function is optional, but it can be useful for IDEs
to provide better intellisense and type checking.
@example 
// studiocms.config.mjs
import { defineStudioCMSConfig } from 'studiocms/config';


export default defineStudioCMSConfig({
 dbStartPage: true,
 // ...Other Options
})
defineStudioCMSConfig({
    
StudioCMSOptions.dbStartPage?: boolean
Project Initialization Page - Used during First Time Setup to initialize the database
@default ― true
dbStartPage: false,
    
StudioCMSOptions.plugins?: StudioCMSPlugin[]
Add Plugins to the StudioCMS
plugins: [
        
function blog(options?: StudioCMSBlogOptions): StudioCMSPlugin
Creates and configures the StudioCMS Blog plugin.
@param ― options - Optional configuration options for the blog plugin.
@returns ― The configured StudioCMS plugin.
@example 
const blogPlugin = studioCMSBlogPlugin({
  blog: {
    title: 'My Blog',
    enableRSS: true,
    route: '/my-blog'
  },
  sitemap: true,
  injectRoutes: true
});
@param ― options.blog - Blog-specific options.
@param ― options.blog.title - The title of the blog. Defaults to 'Blog'.
@param ― options.blog.enableRSS - Whether to enable RSS feed. Defaults to true.
@param ― options.blog.route - The route for the blog. Defaults to '/blog'.
@param ― options.sitemap - Whether to trigger sitemap generation. Defaults to true.
@param ― options.injectRoutes - Whether to inject routes for the blog. Defaults to true.
blog(),
    ],
});

Building and deploying your StudioCMS project

Section titled “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

Section titled “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.