Skip to content
StudioCMS Docs
Main Site
Live Demo

Getting Started

Let’s get started

'Read the “', Let’s get started, '” section'

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

'Read the “', Prepare your database, '” section'

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

'Read the “', Getting started with Turso, '” section'

  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 ASTRO_DB_REMOTE_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 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:

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

'Read the “', Using another provider or self-hosted libSQL, '” section'

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

'Read the “', Creating a StudioCMS project, '” section'

  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 { 
    function defineConfig<const TLocales extends Locales = never, const TDriver extends SessionDriverName = never>(config: AstroUserConfig<TLocales, TDriver>): AstroUserConfig<TLocales, TDriver>
    See the full Astro Configuration API Documentation
https://astro.build/config
    defineConfig     } from 'astro/config';
    import 
    function db(): AstroIntegration[]
    db     from '@astrojs/db';
    import 
    function node(userOptions: UserOptions): AstroIntegration
    node     from '@astrojs/node';
    import 
    const studioCMS: (options?: {
        sdk?: boolean | {
            cacheConfig?: boolean | {
                lifetime?: string | undefined;
            } | undefined;
        } | undefined;
        dbStartPage?: boolean | undefined;
        imageService?: {
            cdnPlugin?: "cloudinary-js" | undefined;
        } | undefined;
        defaultFrontEndConfig?: boolean | {
            htmlDefaultLanguage?: string | undefined;
            htmlDefaultHead?: {
                tag: "link" | "title" | "base" | "style" | "meta" | "script" | "noscript" | "template";
                attrs?: Record<string, string | boolean | undefined> | undefined;
                content?: string | undefined;
            }[] | undefined;
            favicon?: string | undefined;
            injectQuickActionsMenu?: boolean | undefined;
        } | undefined;
        dashboardConfig?: {
            dashboardEnabled?: boolean | undefined;
            inject404Route?: boolean | undefined;
            faviconURL?: string | undefined;
            dashboardRouteOverride?: string | undefined;
            AuthConfig?: {
                providers?: {
                    github?: boolean | undefined;
                    discord?: boolean | undefined;
                    google?: boolean | undefined;
                    auth0?: boolean | undefined;
                    usernameAndPassword?: boolean | undefined;
                    usernameAndPasswordConfig?: {
                        allowUserRegistration?: boolean | undefined;
                    } | undefined;
                } | undefined;
                enabled?: boolean | undefined;
            } | undefined;
            developerConfig?: {
                demoMode?: false | {
                    password: string;
                    username ...
    StudioCMS Integration
    

    A CMS built for Astro by the Astro Community for the Astro Community.
    @see ― The GitHub Repo: withstudiocms/studiocms for more information on how to contribute to StudioCMS.
    @see ― The StudioCMS Docs for more information on how to use StudioCMS.
    studioCMS     from 'studiocms';
    

    export default 
    defineConfig<never, never>(config: AstroUserConfig<never, never>): AstroUserConfig<never, never>
    See the full Astro Configuration API Documentation
https://astro.build/config
    defineConfig    ({
        
    AstroUserConfig<TLocales extends Locales = never, TSession extends SessionDriverName = never>.site?: string
    @name ― site
    @type ― {string}
    @description 
    Your final, deployed URL. Astro uses this full URL to generate your sitemap and canonical URLs in your final build. It is strongly recommended that you set this configuration to get the most out of Astro.
    

    {
      site: 'https://www.my-site.dev'
    }
    site    : 'https://demo.studiocms.dev/',
        
    AstroUserConfig<TLocales extends Locales = never, TSession extends SessionDriverName = never>.output?: "server" | "static"
    @name ― output
    @type ― {('static' | 'server')}
    @default ― 'static'
    @see ― adapter *
    @description 
    Specifies the output target for builds.
    

      

    • 'static' - Prerender all your pages by default, outputting a completely static site if none of your pages opt out of prerendering.
      • 

    • 'server' - Use server-side rendering (SSR) for all pages by default, always outputting a server-rendered site.
      • 

    

    import { defineConfig } from 'astro/config';
    

    export default defineConfig({
      output: 'static'
    })
    output    : 'server',
        
    AstroUserConfig<TLocales extends Locales = never, TSession extends SessionDriverName = never>.adapter?: AstroIntegration
    @name ― adapter
    @see ― output *
    @description 
    Deploy to your favorite server, serverless, or edge host with build adapters. Import one of our first-party adapters for Netlify, Vercel, and more to engage Astro SSR.
    

    See our On-demand Rendering guide for more on SSR, and our deployment guides for a complete list of hosts.
    

    import netlify from '@astrojs/netlify';
    {
      // Example: Build for Netlify serverless deployment
      adapter: netlify(),
    }
    adapter    : 
    function node(userOptions: UserOptions): AstroIntegration
    node    ({ 
    UserOptions.mode: "standalone" | "middleware"
    Specifies the mode that the adapter builds to.
    

      

    • 'middleware' - Build to middleware, to be used within another Node.js server, such as Express.
      • 

    • 'standalone' - Build to a standalone server. The server starts up just by running the built script.
      • 

    mode    : "standalone" }),
        
    AstroUserConfig<TLocales extends Locales = never, TSession extends SessionDriverName = never>.integrations?: (false | AstroIntegration | (false | AstroIntegration | null | undefined)[] | null | undefined)[]
    @name ― integrations
    @description 
    Extend Astro with custom integrations. Integrations are your one-stop-shop for adding framework support (like Solid.js), new features (like sitemaps), and new libraries (like Partytown).
    

    Read our Integrations Guide for help getting started with Astro Integrations.
    

    import react from '@astrojs/react';
    import mdx from '@astrojs/mdx';
    {
      // Example: Add React + MDX support to Astro
      integrations: [react(), mdx()]
    }
    integrations    : [
            
    function db(): AstroIntegration[]
    db    (),
            
    function studioCMS(options?: {
        sdk?: boolean | {
            cacheConfig?: boolean | {
                lifetime?: string | undefined;
            } | undefined;
        } | undefined;
        dbStartPage?: boolean | undefined;
        imageService?: {
            cdnPlugin?: "cloudinary-js" | undefined;
        } | undefined;
        defaultFrontEndConfig?: boolean | {
            htmlDefaultLanguage?: string | undefined;
            htmlDefaultHead?: {
                tag: "link" | "title" | "base" | "style" | "meta" | "script" | "noscript" | "template";
                attrs?: Record<string, string | boolean | undefined> | undefined;
                content?: string | undefined;
            }[] | undefined;
            favicon?: string | undefined;
            injectQuickActionsMenu?: boolean | undefined;
        } | undefined;
        dashboardConfig?: {
            dashboardEnabled?: boolean | undefined;
            inject404Route?: boolean | undefined;
            faviconURL?: string | undefined;
            dashboardRouteOverride?: string | undefined;
            AuthConfig?: {
                providers?: {
                    github?: boolean | undefined;
                    discord?: boolean | undefined;
                    google?: boolean | undefined;
                    auth0?: boolean | undefined;
                    usernameAndPassword?: boolean | undefined;
                    usernameAndPasswordConfig?: {
                        allowUserRegistration?: boolean | undefined;
                    } | undefined;
                } | undefined;
                enabled?: boolean | undefined;
            } | undefined;
            developerConfig?: {
                demoMode?: false | {
                    password: string;
                    username ...
    StudioCMS Integration
    

    A CMS built for Astro by the Astro Community for the Astro Community.
    @see ― The GitHub Repo: withstudiocms/studiocms for more information on how to contribute to StudioCMS.
    @see ― The StudioCMS Docs for more information on how to use StudioCMS.
    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.xyz/ or http://localhost:4321/)

Configure authentication

'Read the “', Configure authentication, '” section'

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

'Read the “', Optional: Configure oAuth authentication, '” section'

StudioCMS supports oAuth authentication with GitHub, Discord, Google, and Auth0. To configure oAuth authentication, you’ll need to set the required environment variables in your .env file, and ensure that the provider is enabled in your config.

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

'Read the “', Setting up the callback URL, '” section'

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

'Read the “', Example callback URL paths, '” section'

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

'Read the “', Configure your package.json scripts, '” section'

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

'Read the “', Running your StudioCMS project, '” section'

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)

'Read the “', First time Setup (or during updates if the tables schema is updated), '” section'

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

Terminal window
npx astro db push --remote
Terminal window
npm run dev --remote

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

'Read the “', Running in Astro Development mode locally, '” section'

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

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

'Read the “', Adding a frontend to your StudioCMS project, '” section'

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

'Read the “', Setup a blog, '” section'

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:

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): {
    sdk?: boolean | {
        cacheConfig?: boolean | {
            lifetime?: string | undefined;
        } | undefined;
    } | undefined;
    dbStartPage?: boolean | undefined;
    imageService?: {
        cdnPlugin?: "cloudinary-js" | undefined;
    } | undefined;
    defaultFrontEndConfig?: boolean | {
        htmlDefaultLanguage?: string | undefined;
        htmlDefaultHead?: {
            tag: "link" | "title" | "base" | "style" | "meta" | "script" | "noscript" | "template";
            attrs?: Record<string, string | boolean | undefined> | undefined;
            content?: string | undefined;
        }[] | undefined;
        favicon?: string | undefined;
        injectQuickActionsMenu?: boolean | undefined;
    } | undefined;
    dashboardConfig?: {
        dashboardEnabled?: boolean | undefined;
        inject404Route?: boolean | undefined;
        faviconURL?: string | undefined;
        dashboardRouteOverride?: string | undefined;
        AuthConfig?: {
            providers?: {
                github?: boolean | undefined;
                discord?: boolean | undefined;
                google?: boolean | undefined;
                auth0?: boolean | undefined;
                usernameAndPassword?: boolean | undefined;
                usernameAndPasswordConfig?: {
                    allowUserRegistration?: boolean | undefined;
                } | undefined;
            } | undefined;
            enabled?: boolean | undefined;
        } | undefined;
        developerConfig?: {
            demoMode?: false | {
                password: string ...
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';


export default defineStudioCMSConfig({
 dbStartPage: true,
 contentRenderer: 'marked',
 verbose: true,
 dateLocale: 'en-us',
 // ...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): {
    sdk?: boolean | {
        cacheConfig?: boolean | {
            lifetime?: string | undefined;
        } | undefined;
    } | undefined;
    dbStartPage?: boolean | undefined;
    imageService?: {
        cdnPlugin?: "cloudinary-js" | undefined;
    } | undefined;
    defaultFrontEndConfig?: boolean | {
        htmlDefaultLanguage?: string | undefined;
        htmlDefaultHead?: {
            tag: "link" | "title" | "base" | "style" | "meta" | "script" | "noscript" | "template";
            attrs?: Record<string, string | boolean | undefined> | undefined;
            content?: string | undefined;
        }[] | undefined;
        favicon?: string | undefined;
        injectQuickActionsMenu?: boolean | undefined;
    } | undefined;
    dashboardConfig?: {
        dashboardEnabled?: boolean | undefined;
        inject404Route?: boolean | undefined;
        faviconURL?: string | undefined;
        dashboardRouteOverride?: string | undefined;
        AuthConfig?: {
            providers?: {
                github?: boolean | undefined;
                discord?: boolean | undefined;
                google?: boolean | undefined;
                auth0?: boolean | undefined;
                usernameAndPassword?: boolean | undefined;
                usernameAndPasswordConfig?: {
                    allowUserRegistration?: boolean | undefined;
                } | undefined;
            } | undefined;
            enabled?: boolean | undefined;
        } | undefined;
        developerConfig?: {
            demoMode?: false | {
                password: string ...
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';


export default defineStudioCMSConfig({
 dbStartPage: true,
 contentRenderer: 'marked',
 verbose: true,
 dateLocale: 'en-us',
 // ...Other Options
})
defineStudioCMSConfig({
    
dbStartPage?: boolean | undefined
dbStartPage: false,
    
plugins?: StudioCMSPlugin[] | undefined
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

'Read the “', Building and deploying your StudioCMS project, '” section'

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

'Read the “', Next steps, '” section'

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.