Zum Inhalt springen

Erste Schritte

Um StudioCMS zu benutzen, brauchst du:

StudioCMS verwendet @astrojs/db, um sich mit deiner libSQL-Datenbank zu verbinden. Du kannst jeden libSQL-Anbieter oder einen selbst gehosteten libSQL-Server verwenden.

Wenn du die StudioCMS CLI verwendest, kannst du diesen Schritt überspringen und die CLI verwenden, um eine neue Datenbank zu erstellen, wenn du die Turso CLI installiert hast.

Weitere Informationen zu den erforderlichen Umgebungsvariablen findest du unter Datenbank-URL und Token für @astrojs/db.
  1. Installiere das Turso CLI ^

  2. Melde dich an oder registriere dich ^ bei Turso.

  3. Erstelle eine neue Datenbank.

    Terminal-Fenster
    turso db create studiocms
  4. Erhalte und setze ASTRO_DB_REMOTE_URL

    4a. Führe den Befehl show aus, um Informationen über die neu erstellte Datenbank zu erhalten:

    Terminal-Fenster
    turso db show studiocms

    4b. Kopiere den URL-Wert und setze ihn als Wert für ASTRO_DB_REMOTE_URL.

    .env
    ASTRO_DB_REMOTE_URL=libsql://studiocms-yourname.turso.io
  5. Erhalte und setze ASTRO_DB_APP_TOKEN

    5a. Erstelle ein neues Token, um Anfragen an die Datenbank zu authentifizieren:

    Terminal-Fenster
    turso db tokens create studiocms

    5b. Kopiere die Ausgabe des Befehls und setze sie als Wert für ASTRO_DB_APP_TOKEN.

    .env
    ASTRO_DB_APP_TOKEN=eyJhbGciOiJF...3ahJpTkKDw

Jetzt kannst du mit der Einrichtung deines StudioCMS-Projekts fortfahren!

Verwendung eines anderen Anbieters oder einer selbst gehosteten libSQL

Abschnitt betitelt „Verwendung eines anderen Anbieters oder einer selbst gehosteten libSQL“

libSQL unterstützt sowohl HTTP als auch WebSockets als Transportprotokoll für einen entfernten Server. Sie unterstützt auch die Verwendung einer lokalen Datei oder einer In-Memory-DB.

Weitere Informationen zu den erforderlichen Umgebungsvariablen findest du unter Datenbank-URL und Token für @astrojs/db.
Weitere Informationen zu allen möglichen libSQL-Optionen (einschließlich lokaler Dateien) findest du unter [den Astro Dokumentationen: Optionen zur Konfiguration der Remote-URL].(https://docs.astro.build/de/guides/astro-db/#remote-url-configuration-options^)
  1. Erstellen eines StudioCMS-Projekts mit dem Befehl create

    Um mit StudioCMS ein neues Astro-Projekt mit einer unserer vorgefertigten Vorlagen zu erstellen, führst du einfach den folgenden Befehl in deinem Terminal aus:

    Terminal-Fenster
    npm create studiocms@latest

    Nachdem du den Befehl ausgeführt hast, wirst du aufgefordert, ein paar Fragen zu deinem Projekt zu beantworten. Danach erstellt das CLI ein neues Astro-Projekt mit StudioCMS im angegebenen Verzeichnis.

    Danach wirst du aufgefordert, die nächsten Schritte zu befolgen. Dazu gehört, dass du sicherstellst, dass deine Umgebungsvariablen richtig gesetzt sind und dass du das Projekt ausführst, um die Einrichtung abzuschließen.

  2. Nachdem du das CLI ausgeführt hast, vergewissere dich, dass deine astro.config.mjs-Datei richtig konfiguriert ist:

    astro.config.mjs
    import {
    function defineConfig<const TLocales extends Locales = never, const TDriver extends SessionDriverName = never, const TFontFamilies extends FontFamily[] = never>(config: AstroUserConfig<TLocales, TDriver, TFontFamilies>): AstroUserConfig<TLocales, TDriver, TFontFamilies>

    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.

    @seeThe GitHub Repo: withstudiocms/studiocms for more information on how to contribute to StudioCMS.

    @seeThe StudioCMS Docs for more information on how to use StudioCMS.

    studioCMS
    from 'studiocms';
    export default
    defineConfig<never, never, never>(config: AstroUserConfig<never, never, never>): AstroUserConfig<never, never, never>

    See the full Astro Configuration API Documentation https://astro.build/config

    defineConfig
    ({
    AstroUserConfig<TLocales extends Locales = never, TSession extends SessionDriverName = never, TFontFamilies extends FontFamily[] = never>.site?: string

    @namesite

    @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, TFontFamilies extends FontFamily[] = never>.output?: "server" | "static"

    @nameoutput

    @type{('static' | 'server')}

    @default'static'

    @seeadapter *

    @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, TFontFamilies extends FontFamily[] = never>.adapter?: AstroIntegration

    @nameadapter

    @seeoutput *

    @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, TFontFamilies extends FontFamily[] = never>.integrations?: (false | AstroIntegration | (false | AstroIntegration | null | undefined)[] | null | undefined)[]

    @nameintegrations

    @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.

    @seeThe GitHub Repo: withstudiocms/studiocms for more information on how to contribute to StudioCMS.

    @seeThe StudioCMS Docs for more information on how to use StudioCMS.

    studioCMS
    (),
    ],
    });

Bitte beachte, dass die Option site in der Datei astro.config.mjs erforderlich ist, damit StudioCMS korrekt funktioniert. Du kannst hier die URL deiner Website oder eine Platzhalter-URL angeben. (z.B. https://demo.studiocms.dev/ oder http://localhost:4321/)

StudioCMS Auth benötigt mindestens den Encryption Key, der in deiner .env Datei gesetzt sein muss.

Die folgenden Umgebungsvariablen sind für die StudioCMS-Authentifizierung erforderlich:

.env
# Verschlüsselungsschlüssel für die Authentifizierung mit Benutzernamen und Passwort
CMS_ENCRYPTION_KEY="wqR+w...sRcg=="

Du kannst einen sicheren Verschlüsselungsschlüssel mit dem folgenden Befehl erzeugen:

Terminal-Fenster
openssl rand --base64 16

Und setze die Ausgabe als Wert für CMS_ENCRYPTION_KEY.

Weitere Informationen über alle verfügbaren Umgebungsvariablen für die Authentifizierung findest du auf der Seite Umgebungsvariablen.

Optional: Konfiguriere die oAuth-Authentifizierung

Abschnitt betitelt „Optional: Konfiguriere die oAuth-Authentifizierung“

StudioCMS unterstützt die oAuth-Authentifizierung mit GitHub, Discord, Google und Auth0. Um die oAuth-Authentifizierung zu konfigurieren, musst du die erforderlichen Umgebungsvariablen in deiner .env-Datei setzen und sicherstellen, dass der Provider in deiner Konfiguration aktiviert ist.

Um oAuth-Anbieter einzurichten, benötigen sie eine Callback-URL. Die Callback-URL ist der Pfad, an den der Anbieter den Nutzer nach der Authentifizierung weiterleiten wird.

Die Callback-URL sollte je nach deiner Umgebung auf einen der folgenden Pfade gesetzt werden:

UmgebungCallback-URL
Produktionhttps://your-domain.tld/studiocms_api/auth/<provider>/callback
Testen & Entwickelunghttp://localhost:4321/studiocms_api/auth/<provider>/callback

Die folgenden Pfade sind Beispiele für die Callback-URL für jeden Anbieter:

AnbieterCallback-Pfad
GitHub/studiocms_api/auth/github/callback
Discord/studiocms_api/auth/discord/callback
Google/studiocms_api/auth/google/callback
Auth0/studiocms_api/auth/auth0/callback

Richte deine package.json-Skripte so ein, dass sie das --remote-Flag für Build und optional für die Entwicklung enthalten. (Du kannst den Entwicklungsbefehl auch so ausführen, wie im Abschnitt „Ausführen deines StudioCMS-Projekts“ gezeigt).

package.json
{
"name": "my-studiocms-project",
"scripts": {
"dev": "astro dev --remote",
"build": "astro check & astro build --remote",
"astro": "astro"
}
}

Dank der Leistungsfähigkeit von Astro ist der Betrieb von StudioCMS so einfach wie das Ausführen des Entwickelungsbefehls für die lokale Vorschau oder das Erstellen und Bereitstellen auf deinem Server.

Erstmalige Einrichtung (oder bei Aktualisierungen, wenn das Tabellenschema aktualisiert wird)

Abschnitt betitelt „Erstmalige Einrichtung (oder bei Aktualisierungen, wenn das Tabellenschema aktualisiert wird)“

Um dein Astro-Projekt zu starten, führe die folgenden Befehle in deinem Terminal aus:

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

Nachdem du die Befehle ausgeführt hast, solltest du eine Meldung sehen, die besagt, dass dein Projekt unter localhost:4321 läuft. Wenn du StudioCMS zum ersten Mal einrichtest, wirst du aufgefordert, die Konfiguration von StudioCMS unter http://localhost:4321/start abzuschließen.

Um dein Astro-Projekt zu starten, führe den folgenden Befehl in deinem Terminal aus:

Terminal-Fenster
npm run dev --remote

Nachdem du den Befehl ausgeführt hast, solltest du eine Meldung sehen, die besagt, dass dein Projekt unter localhost:4321 läuft. Öffne deinen Browser und navigiere zu http://localhost:4321, um dein Astro-Projekt in Aktion zu sehen.

Glückwunsch! 🥳 Du hast jetzt StudioCMS in deinem Astro-Projekt installiert.

Hinzufügen eines Frontends zu deinem StudioCMS-Projekt

Abschnitt betitelt „Hinzufügen eines Frontends zu deinem StudioCMS-Projekt“

StudioCMS ist ein Headless Astro CMS, d.h. du musst dein eigenes Frontend bereitstellen, um die Inhalte anzuzeigen. Wenn du ein bereits fertiges Frontend suchst, kannst du unsere Plugins im Paket-Katalog ausprobieren.

Wenn du einen Blog einrichten möchtest, kannst du das Plugin @studiocms/blog verwenden.

Um das Blog-Plugin zu installieren und einzurichten, führe den folgenden Befehl in deinem Terminal aus:

Terminal-Fenster
npm install @studiocms/blog

Nachdem du das Plugin installiert hast, musst du es zu deiner Datei studiocms.config.mjs hinzufügen:

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.

@paramoptions - Optional configuration options for the blog plugin.

@returnsThe configured StudioCMS plugin.

@example

const blogPlugin = studioCMSBlogPlugin({
blog: {
title: 'My Blog',
enableRSS: true,
route: '/my-blog'
},
sitemap: true,
injectRoutes: true
});

@paramoptions.blog - Blog-specific options.

@paramoptions.blog.title - The title of the blog. Defaults to 'Blog'.

@paramoptions.blog.enableRSS - Whether to enable RSS feed. Defaults to true.

@paramoptions.blog.route - The route for the blog. Defaults to '/blog'.

@paramoptions.sitemap - Whether to trigger sitemap generation. Defaults to true.

@paramoptions.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.

@paramoptions - Optional configuration options for the blog plugin.

@returnsThe configured StudioCMS plugin.

@example

const blogPlugin = studioCMSBlogPlugin({
blog: {
title: 'My Blog',
enableRSS: true,
route: '/my-blog'
},
sitemap: true,
injectRoutes: true
});

@paramoptions.blog - Blog-specific options.

@paramoptions.blog.title - The title of the blog. Defaults to 'Blog'.

@paramoptions.blog.enableRSS - Whether to enable RSS feed. Defaults to true.

@paramoptions.blog.route - The route for the blog. Defaults to '/blog'.

@paramoptions.sitemap - Whether to trigger sitemap generation. Defaults to true.

@paramoptions.injectRoutes - Whether to inject routes for the blog. Defaults to true.

blog
(),
],
});

Erstellen und Bereitstellen deines StudioCMS-Projekts

Abschnitt betitelt „Erstellen und Bereitstellen deines StudioCMS-Projekts“

Nachdem du die Schritte für die Ersteinrichtung ausgeführt hast, solltest du dein StudioCMS-Projekt erstellen und auf deinem Server bereitstellen.

Standardmäßig ist das Dashboard von StudioCMS unter http://your-domain.tld/dashboard verfügbar.

Dieses Dashboard steht dir zur Verfügung, um deine Inhalte und Einstellungen im Entwicklungs- und Produktionsmodus zu verwalten.

Es wird empfohlen, StudioCMS nur im Produktionsmodus zu verwenden, da das Dashboard für das erstellte Projekt gedacht ist. (Im Entwicklungsmodus können einige Probleme/Fehler auftreten, z. B. ein Vite Entwicklungsfehler).

Hier erfährst du, wie du Umgebungsvariablen in StudioCMS einstellst.

Schau dir den Paketkatalog an, um Plugins mit StudioCMS zu finden und zu verwenden.

Mehr über die StudioCMS-Konfigurationsoptionen erfährst du auf den Seiten StudioCMS Referenz.