Saltearse al contenido
StudioCMS Docs
Sitio Principal

Comienza aquí

Actualizar StudioCMS a la última versión ¿Quieres actualizar a la última versión? ¡Aquí tienes!

Vamos a empezar

Sección titulada «Vamos a empezar»

Para empezar a usar StudioCMS, necesitarás:

  • Una versión de Node.js soportada por Astro^ (Bun y Deno no son soportados)
  • Un proyecto Astro
  • Una conexión a la base de datos (libSQL, MySQL, o PostgreSQL)
  • La integración StudioCMS

Prepara tu base de datos

Sección titulada «Prepara tu base de datos»

  1. Instala el Turso CLI ^

  2. Iniciar sesión o registrarse ^ en Turso.

  3. Crea una nueva base de datos.

    Ventana de terminal
    turso db create studiocms

  4. Obtén y establece CMS_LIBSQL_URL

    4a. Ejecuta el comando show para ver información sobre la base de datos recién creada:

    Ventana de terminal
    turso db show studiocms

    4b. Copia el valor de la URL y establece el valor para CMS_LIBSQL_URL.

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

  5. Obtén y establece CMS_LIBSQL_AUTH_TOKEN

    5a. Crea un nuevo token para autenticar solicitudes a la base de datos:

    Ventana de terminal
    turso db tokens create studiocms

    5b. Copia la salida del comando y establece el valor para CMS_LIBSQL_AUTH_TOKEN.

    .env
    CMS_LIBSQL_AUTH_TOKEN=eyJhbGciOiJF...3ahJpTkKDw

¡Estás ahora listo para pasar a crear tu proyecto StudioCMS!

Crear un proyecto StudioCMS

Sección titulada «Crear un proyecto StudioCMS»

  1. Crear un proyecto de StudioCMS usando el comando create

    Para crear un nuevo proyecto Astro con StudioCMS usando uno de nuestros templates pre-hechos, simplemente ejecuta el siguiente comando en tu terminal:

    Ventana de terminal
    npm create studiocms@latest

    Después de ejecutar el comando, se te pedirá que respondas a algunas preguntas sobre tu proyecto. Una vez completado, el CLI creará un nuevo proyecto Astro con StudioCMS en el directorio especificado.

    Posteriormente, se te pedirá que sigas los siguientes pasos, que incluyen asegurarte de que tus variables de entorno están configuradas correctamente y ejecutar el proyecto para completar la configuración.

  2. Después de ejecutar el CLI, asegúrate de que tu archivo astro.config.mjs está correctamente configurado:

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

Ten en cuenta que la opción site en el archivo astro.config.mjs es requerida para que StudioCMS funcione correctamente. Puedes establecer esto en la URL de tu sitio o en una URL de marcador de posición. (es decir, https://demo.studiocms.dev/ o http://localhost:4321/)

Configurar el dialecto de la base de datos de StudioCMS Añadido en beta.31

Sección titulada «Configurar el dialecto de la base de datos de StudioCMS »

Si estás usando una base de datos diferente a libSQL, necesitarás configurar la opción db en tu archivo studiocms.config.mjs para especificar el dialecto correcto.

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'
  },
})

Asegurar que los paquetes de cliente de base de datos están instalados

Sección titulada «Asegurar que los paquetes de cliente de base de datos están instalados»

También necesitarás instalar los paquetes de cliente de base de datos necesarios para el dialecto de base de datos que has elegido:

Ventana de terminal
npm i @libsql/client kysely-turso

Configurar el renderizado de StudioCMS Añadido en beta.22

Sección titulada «Configurar el renderizado de StudioCMS »

StudioCMS requiere al menos uno de los siguientes plugins de renderizado para ser instalado y configurado dentro de tu proyecto StudioCMS:

Cualquiera de estos plugins puede ser usado para renderizar contenido en StudioCMS. Puedes usar uno o más de estos plugins en tu proyecto, dependiendo de tus necesidades. Pueden ser instalados y configurados usando el archivo de configuración de StudioCMS.

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(),
    ],
});
Para más información sobre los plugins de renderizado disponibles, consulta Catálogo de Paquetes

Configurar la autenticación

Sección titulada «Configurar la autenticación»

La autenticación incorporada de StudioCMS requiere al menos la Clave de Encriptación para ser establecida en tu archivo .env.

Las siguientes variables de entorno son requeridas para la autenticación de StudioCMS:

.env
# clave de encriptación para autenticación por nombre de usuario y contraseña
CMS_ENCRYPTION_KEY="wqR+w...sRcg=="

Puedes generar una clave de encriptación segura usando el siguiente comando:

Ventana de terminal
openssl rand --base64 16

Y establece la salida como el valor para CMS_ENCRYPTION_KEY.

Para más información sobre todas las variables de entorno disponibles para la autenticación, consulta la página Variables de entorno.

Opcional: Configurar la autenticación oAuth Versión beta revisada.23

Sección titulada «Opcional: Configurar la autenticación oAuth »

StudioCMS soporta varios proveedores de autenticación oAuth, utilizando nuestro sistema de plugins para habilitar los proveedores que quieres usar. Para empezar, necesitarás encontrar un plugin para el proveedor que quieres usar, o crear tu propio plugin.

Para más información sobre los plugins de autenticación oAuth disponibles, consulta Catálogo de Paquetes

Para configurar proveedores oAuth, necesitan una URL de devolución de llamada. La URL de devolución de llamada es la ruta donde el proveedor redirigirá al usuario después de la autenticación.

Configurando la URL de devolución de llamada
Sección titulada «Configurando la URL de devolución de llamada»

La URL de devolución de llamada debe ser establecida en uno de los siguientes paths basado en tu entorno:

EntornoURL de devolución de llamada
Productionhttps://your-domain.tld/studiocms_api/auth/<provider>/callback
Testing & Devhttp://localhost:4321/studiocms_api/auth/<provider>/callback
Ejemplos de paths de URL de devolución de llamada
Sección titulada «Ejemplos de paths de URL de devolución de llamada»

Los siguientes paths son ejemplos de la URL de devolución de llamada para cada proveedor:

ProveedorPATH de devolución de llamada
GitHub/studiocms_api/auth/github/callback
Discord/studiocms_api/auth/discord/callback
Google/studiocms_api/auth/google/callback
Auth0/studiocms_api/auth/auth0/callback

Configurar el Gestor de API de Almacenamiento (opcional) Añadido en v0.1.0

Sección titulada «Configurar el Gestor de API de Almacenamiento (opcional) »

StudioCMS soporta el uso de diferentes Gestionadores de API de Almacenamiento para manejar el almacenamiento de archivos y imágenes. Por defecto, StudioCMS usa un gestor de almacenamiento incorporado que no almacena ningún archivo o imagen.

Para configurar un diferente Gestor de API de Almacenamiento, necesitarás instalar el plugin adecuado y configurarlo en tu archivo studiocms.config.mjs.

Para más información sobre la API de Almacenamiento, consulta la Documentación de la API de Almacenamiento
Para más información sobre los plugins de gestión de almacenamiento disponibles, consulta el Catálogo de Paquetes.

Ejemplo: Configurar el Gestor de Almacenamiento S3

Sección titulada «Ejemplo: Configurar el Gestor de Almacenamiento S3»

  1. Instala el plugin @studiocms/s3-storage:

    Ventana de terminal
    npm i @studiocms/s3-storage

  2. Actualiza tu archivo studiocms.config.mjs para usar el Gestor de Almacenamiento S3:

    studiocms.config.mjs
    import { defineStudioCMSConfig } from 'studiocms/config';
    import s3Storage from '@studiocms/s3-storage';
    

    export default defineStudioCMSConfig({
       storageManager: s3Storage(),
    });

  3. Establece las variables de entorno requeridas para el Gestor de Almacenamiento S3 en tu archivo .env:

    .env
    CMS_S3_PROVIDER=ProveedorS3Ejemplo
    CMS_S3_ACCESS_KEY_ID=<id-de-acceso-de-tu-clave>
    CMS_S3_SECRET_ACCESS_KEY=<contraseña-de-acceso-secreta>
    CMS_S3_BUCKET_NAME=<nombre-del-bucket>
    # CMS_S3_ENDPOINT= # Opcional: Especifica un endpoint personalizado si es requerido por tu proveedor
    # CMS_S3_REGION= # Opcional: Especifica la región si es requerido por tu proveedor
    # CMS_S3_FORCE_PATH_STYLE= # Opcional: Usar URLs de estilo de ruta para objetos S3
    # CMS_S3_PUBLIC_ENDPOINT= # Opcional: Endpoint público personalizado para acceder a los archivos
    Para más información sobre las variables de entorno con el Gestor de Almacenamiento S3, consulta Almacenamiento S3: Variables de entorno

Configurar tus scripts de package.json

Sección titulada «Configurar tus scripts de package.json»

Configura tus scripts de package.json para incluir los siguientes comandos de StudioCMS para un uso más fácil:

package.json
{
    "name": "mi-proyecto-studiocms",
    "scripts": {
        "dev": "astro dev",
        "build": "astro check & astro build",
        "astro": "astro",
        "migrate": "studiocms migrate",
        "studiocms": "studiocms",
    }
}

Ejecutar tu proyecto StudioCMS

Sección titulada «Ejecutar tu proyecto StudioCMS»

Gracias al poder de Astro, ejecutar StudioCMS es tan fácil como ejecutar el comando dev para una vista previa local, o construir y desplegar a tu servidor. Para las bases de cómo usarlo localmente sin construir, aquí es lo que necesitas hacer.

Primera configuración (o durante actualizaciones si el esquema de tablas es actualizado)

Sección titulada «Primera configuración (o durante actualizaciones si el esquema de tablas es actualizado)»

Para iniciar tu proyecto Astro, ejecuta los siguientes comandos en tu terminal:

Ventana de terminal
npm run studiocms migrate --latest
Ventana de terminal
npm run dev

Después de ejecutar los comandos, deberías ver un mensaje indicando que tu proyecto está ejecutándose en localhost:4321. Cuando estés configurando StudioCMS por primera vez, se te pedirá que completes la configuración de StudioCMS en http://localhost:4321/start

Ejecutando en modo de desarrollo Astro localmente

Sección titulada «Ejecutando en modo de desarrollo Astro localmente»

Para iniciar tu proyecto Astro, ejecuta el siguiente comando en tu terminal:

Ventana de terminal
npm run dev

Después de ejecutar el comando, deberías ver un mensaje indicando que tu proyecto está ejecutándose en localhost:4321. Abre tu navegador y navega a http://localhost:4321 para ver tu proyecto Astro en acción.

Puedes acceder al panel de control de StudioCMS en http://localhost:4321/dashboard por defecto para gestionar tu contenido y configuraciones.

¡Felicidades! 🥳 Ahora tienes StudioCMS instalado en tu proyecto Astro.

Añadir un frontend a tu proyecto StudioCMS

Sección titulada «Añadir un frontend a tu proyecto StudioCMS»

StudioCMS es un CMS Astro sin cabeza, lo que significa que tienes que proporcionar tu propio frontend para mostrar el contenido. Si estás buscando un frontend que ya esté construido, puedes consultar nuestros plugins en el Catálogo de Paquetes.

Configurar un blog

Sección titulada «Configurar un blog»

Por ejemplo, si quieres construir un blog usando StudioCMS, puedes usar el plugin @studiocms/blog para empezar rápidamente sin tener que construir todo desde cero. Este plugin proporciona un frontend de blog simple que elimina la necesidad de tener ningún archivo fuente para tus páginas de frontend.

Para instalar y configurar el plugin de blog, ejecuta el siguiente comando en tu terminal:

Ventana de terminal
npm install @studiocms/blog

Después de instalar el plugin, necesitarás añadir el plugin a tu archivo studiocms.config.mjs:

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

Construir un frontend personalizado

Sección titulada «Construir un frontend personalizado»

Si quieres construir un frontend personalizado para tu proyecto StudioCMS, puedes usar el SDK de StudioCMS o API Rest de StudioCMS para obtener contenido y un plugin de renderizado de StudioCMS para renderizar contenido de StudioCMS en tus páginas personalizadas.

Si quieres construir un frontend personalizado para tu proyecto StudioCMS, puedes usar el componente Renderer y SDK de StudioCMS para renderizar el contenido de StudioCMS en tus páginas personalizadas.

Consulta las Guías de Frontend Personalizado para más guías y tutoriales sobre cómo construir un frontend personalizado con StudioCMS.

Construir y desplegar tu proyecto StudioCMS

Sección titulada «Construir y desplegar tu proyecto StudioCMS»

Después de ejecutar los pasos de primera configuración, deberías construir y desplegar tu proyecto StudioCMS a tu servidor.

Por defecto, el panel de control de StudioCMS está disponible en http://your-domain.tld/dashboard.

Este panel de control estará disponible para ti para gestionar tu contenido y configuraciones en modo de desarrollo y producción.

Se recomienda usar StudioCMS en modo de producción solo, ya que el panel de control está diseñado para ser usado por el proyecto construido. (Es posible que veas algunos problemas/errores en modo de desarrollo, como un error de dependencia de Vite.)

Próximos pasos

Sección titulada «Próximos pasos»

Consulta cómo configurar Variables de entorno en StudioCMS.

Consulta el Catálogo de Paquetes para encontrar y usar plugins con StudioCMS.

Aprende más sobre las opciones de configuración de StudioCMS usando las páginas Referencia de StudioCMS.