Aller au contenu
StudioCMS Docs
Site principal

Mise en route

Mise à niveau de StudioCMS vers la dernière version Vous souhaitez mettre à niveau vers la version la plus récente ? Regardez ici !

C’est parti

Section intitulée « C’est parti »

Pour commencer à utiliser StudioCMS, vous aurez besoin de :

  • Une version de Node.js prise en charge par Astro^ (Bun et Deno ne sont pas pris en charge)
  • Un projet Astro
  • Une connexion à une base de données (libSQL, MySQL ou PostgreSQL)
  • L’intégration StudioCMS

Préparer votre base de données

Section intitulée « Préparer votre base de données »

  1. Installez la CLI de Turso ^

  2. Se connecter ou s'inscrire ^ à Turso.

  3. Créer une nouvelle base de données.

    Fenêtre de terminal
    turso db create studiocms

  4. Obtenez et définissez CMS_LIBSQL_URL

    4a. Exécutez la commande show pour afficher les informations relatives à la base de données nouvellement créée :

    Fenêtre de terminal
    turso db show studiocms

    4b. Copiez la valeur de l’URL et définissez-la comme valeur pour CMS_LIBSQL_URL.

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

  5. Obtenez et définissez CMS_LIBSQL_AUTH_TOKEN

    5a. Créez un nouveau jeton pour authentifier les requêtes auprès de la base de données :

    Fenêtre de terminal
    turso db tokens create studiocms

    5b. Copiez le résultat de la commande et définissez-le comme valeur pour CMS_LIBSQL_AUTH_TOKEN.

    .env
    CMS_LIBSQL_AUTH_TOKEN=eyJhbGciOiJF...3ahJpTkKDw

Vous êtes maintenant prêt à passer à la création de votre projet StudioCMS !

Création d’un projet StudioCMS

Section intitulée « Création d’un projet StudioCMS »

  1. Création d’un projet StudioCMS à l’aide de la commande create

    Pour créer un nouveau projet Astro avec StudioCMS en utilisant l’un de nos modèles prédéfinis, exécutez simplement la commande suivante dans votre terminal :

    Fenêtre de terminal
    npm create studiocms@latest

    Après avoir exécuté la commande, vous serez invité à répondre à quelques questions sur votre projet. Une fois l’opération terminée, l’interface en ligne de commande créera un nouveau projet Astro avec StudioCMS dans le répertoire spécifié.

    Ensuite, vous serez invité à effectuer les étapes suivantes, qui consistent notamment à vous assurer que vos variables d’environnement sont correctement définies et à exécuter le projet pour terminer la configuration.

  2. Après avoir exécuté la CLI, assurez-vous que votre fichier astro.config.mjs est correctement configuré :

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

Veuillez noter que l’option site dans le fichier astro.config.mjs est requise pour que StudioCMS fonctionne correctement. Vous pouvez la définir sur l’URL de votre site ou sur une URL temporaire. (c.-à-d. https://demo.studiocms.dev/ ou http://localhost:4321/)

Configurer le dialecte de la base de données de StudioCMS Ajouté dans la version beta.31

Section intitulée « Configurer le dialecte de la base de données de StudioCMS »

Si vous utilisez une base de données autre que libSQL, vous devrez configurer l’option db dans votre fichier studiocms.config.mjs pour spécifier le bon dialecte.

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

S’assurer que les paquets clients de base de données sont installés

Section intitulée « S’assurer que les paquets clients de base de données sont installés »

Vous devrez également installer les paquets clients de base de données nécessaires pour le dialecte de base de données que vous avez choisi :

Fenêtre de terminal
npm i @libsql/client @libsql/kysely-libsql

Configurer le rendu de StudioCMS Ajouté dans la beta.22

Section intitulée « Configurer le rendu de StudioCMS »

StudioCMS nécessite qu’au moins l’un des modules d’extension de rendu suivants soit installé et configuré dans votre projet StudioCMS :

N’importe lequel de ces modules d’extension peut être utilisé pour afficher du contenu dans StudioCMS. Vous pouvez utiliser un ou plusieurs de ces modules d’extension dans votre projet, selon vos besoins. Ils peuvent être installés et configurés à l’aide du fichier de configuration 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(),
    ],
});
Pour plus d’informations sur les modules d’extension de rendu disponibles, consultez le catalogue des paquets

Configurer l’authentification

Section intitulée « Configurer l’authentification »

L’authentification intégrée de StudioCMS nécessite au moins que la clé de chiffrement soit définie dans votre fichier .env.

Les variables d’environnement suivantes sont requises pour l’authentification StudioCMS :

.env
# clé de chiffrement pour l’authentification par nom d’utilisateur et mot de passe
CMS_ENCRYPTION_KEY="wqR+w...sRcg=="

Vous pouvez générer une clé de chiffrement sécurisée à l’aide de la commande suivante :

Fenêtre de terminal
openssl rand --base64 16

Et utiliser la sortie comme valeur pour CMS_ENCRYPTION_KEY.

Pour plus d’informations sur toutes les variables d’environnement d’authentification disponibles, consultez la page Variables d’environnement.

Facultatif : configurer l’authentification oAuth Révisé dans la bêta.23

Section intitulée « Facultatif : configurer l’authentification oAuth »

StudioCMS prend en charge divers fournisseurs d’authentification oAuth, en utilisant notre système de modules d’extension pour activer les fournisseurs que vous souhaitez utiliser. Pour commencer, vous devrez trouver un module d’extension pour le fournisseur que vous souhaitez utiliser ou créer votre propre module d’extension.

Pour plus d’informations sur les modules d’extension d’authentification oAuth disponibles, consultez le catalogue des paquets

Pour configurer les fournisseurs oAuth, une URL de rappel est nécessaire. Cette URL correspond au chemin vers lequel le fournisseur redirigera l’utilisateur après l’authentification.

Configuration de l’URL de rappel
Section intitulée « Configuration de l’URL de rappel »

L’URL de rappel doit être définie sur l’un des chemins suivants en fonction de votre environnement :

EnvironnementURL de rappel
Productionhttps://votre-domaine.tld/studiocms_api/auth/<provider>/callback
Tests & Devhttp://localhost:4321/studiocms_api/auth/<provider>/callback
Exemples de chemins d’URL de rappel
Section intitulée « Exemples de chemins d’URL de rappel »

Les chemins suivants sont des exemples d’URL de rappel pour chaque fournisseur :

FournisseurChemin de rappel
GitHub/studiocms_api/auth/github/callback
Discord/studiocms_api/auth/discord/callback
Google/studiocms_api/auth/google/callback
Auth0/studiocms_api/auth/auth0/callback

Configurer les scripts de votre package.json

Section intitulée « Configurer les scripts de votre package.json »

Configurez les scripts de votre fichier package.json pour inclure les commandes StudioCMS suivantes afin de faciliter leur utilisation :

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

Exécution de votre projet StudioCMS

Section intitulée « Exécution de votre projet StudioCMS »

Grâce à la puissance d’Astro, exécuter StudioCMS est aussi simple que d’exécuter la commande dev pour obtenir un aperçu local, ou de créer et de déployer sur votre serveur. Pour une utilisation locale de base sans construction, voici ce que vous devez faire.

Première configuration (ou lors des mises à jour si le schéma des tables est mis à jour)

Section intitulée « Première configuration (ou lors des mises à jour si le schéma des tables est mis à jour) »

Pour démarrer votre projet Astro, exécutez les commandes suivantes dans votre terminal :

Fenêtre de terminal
npm run studiocms migrate --latest
Fenêtre de terminal
npm run dev

Après avoir exécuté les commandes, un message devrait s’afficher indiquant que votre projet s’exécute sur localhost:4321. Lors de la première configuration de StudioCMS, vous serez invité à terminer la configuration à l’adresse http://localhost:4321/start.

Exécution locale avec le mode développement d’Astro

Section intitulée « Exécution locale avec le mode développement d’Astro »

Pour démarrer votre projet Astro, exécutez la commande suivante dans votre terminal :

Fenêtre de terminal
npm run dev

Après avoir exécuté la commande, vous devriez voir un message indiquant que votre projet s’exécute sur localhost:4321. Ouvrez votre navigateur et accédez à http://localhost:4321 pour voir votre projet Astro en action.

Vous pouvez accéder par défaut au tableau de bord de StudioCMS à l’adresse http://localhost:4321/dashboard pour gérer votre contenu et vos paramètres.

Félicitations ! 🥳 Vous avez maintenant installé StudioCMS dans votre projet Astro.

Ajouter un frontend à votre projet StudioCMS

Section intitulée « Ajouter un frontend à votre projet StudioCMS »

StudioCMS est un CMS headless pour Astro, ce qui signifie que vous devez fournir votre propre frontend pour afficher le contenu. Si vous recherchez un frontend prêt à l’emploi, vous pouvez consulter nos modules d’extension dans le Catalogue de paquets.

Créer un blog

Section intitulée « Créer un blog »

Par exemple, si vous souhaitez créer un blog à l’aide de StudioCMS, vous pouvez utiliser le module d’extension @studiocms/blog pour démarrer rapidement sans avoir à tout créer à partir de zéro. Ce module d’extension fournit une interface de blog simple qui élimine le besoin d’avoir des fichiers sources pour vos pages frontend.

Pour installer et configurer le module d’extension de blog, exécutez la commande suivante dans votre terminal :

Fenêtre de terminal
npm install @studiocms/blog

Après avoir installé le module d’extension, vous devrez l’ajouter dans votre fichier 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(),
    ],
});

Création d’une interface frontend personnalisée

Section intitulée « Création d’une interface frontend personnalisée »

Si vous souhaitez créer un frontend personnalisé pour votre projet StudioCMS, vous pouvez utiliser le SDK de StudioCMS ou l’API Rest de StudioCMS pour récupérer et un module d’extension de rendu pour StudioCMS afin d’afficher le contenu de StudioCMS sur vos pages personnalisées.

Si vous souhaitez créer un frontend personnalisé pour votre projet StudioCMS, vous pouvez utiliser le composant Renderer et le SDK de StudioCMS pour afficher le contenu de StudioCMS sur vos pages personnalisées.

Consultez les guides des frontend personnalisés pour plus de guides et de tutoriels sur la création d’un frontend personnalisé avec StudioCMS.

Créer et déployer votre projet StudioCMS

Section intitulée « Créer et déployer votre projet StudioCMS »

Après avoir effectué les premières étapes de configuration, vous devriez créer et déployer votre projet StudioCMS sur votre serveur.

Par défaut, le tableau de bord de StudioCMS est disponible à l’adresse http://votre-domaine.tld/dashboard.

Ce tableau de bord sera à votre disposition pour gérer votre contenu et vos paramètres en mode développement et en mode production.

Il est recommandé d’utiliser StudioCMS uniquement en mode production, car le tableau de bord est destiné à être utilisé par le projet compilé. (Vous pourriez rencontrer des problèmes/erreurs en mode développement, comme une erreur de dépendances provenant de Vite.)

Prochaines étapes

Section intitulée « Prochaines étapes »

Découvrez comment définir les Variables d’environnement dans StudioCMS.

Consultez le Catalogue de paquets pour rechercher et utiliser des modules d’extension avec StudioCMS.

Apprenez-en plus sur les options de configuration de StudioCMS à l’aide des pages Référence de StudioCMS.