Los Fundamentos

Introducción

Los complementos de StudioCMS son una herramienta poderosa que te permite extender la funcionalidad de StudioCMS. Proporcionan una manera simple y flexible de agregar nuevas características a tu proyecto StudioCMS. A continuación se muestra un resumen de los complementos de StudioCMS y cómo funcionan.

¿Qué son los complementos?

Los complementos de StudioCMS son similares a las integraciones de Astro, pero tienen información extra adjunta al objeto de la función. Esta información se usa por StudioCMS para determinar cómo se debe cargar y usar el complemento. Los complementos de StudioCMS se usan para extender la funcionalidad de StudioCMS agregando nuevas características o modificando las existentes.

El tipo de complemento de StudioCMS Revisado beta.31

interface StudioCMSPlugin {
  identifier: string;
  name: string;
  studiocmsMinimumVersion: string;
  hooks: {
    'studiocms:astro:config': (params: {
      logger: AstroIntegrationLogger;
      addIntegrations: (args_0: AstroIntegration | AstroIntegration[]) => void;
    }) => void | Promise<void>;
    'studiocms:auth': (params: {
      logger: AstroIntegrationLogger;
      setAuthService: (args_0: { ...; }) => void;
    }) => void | Promise<void>;
    'studiocms:dashboard': (params: {
      logger: AstroIntegrationLogger;
      setDashboard: (args_0: { ...; }) => void;
      augmentDashboard: (args_0: { ...; }) => void;
    }) => void | Promise<void>;
    'studiocms:frontend': (params: {
      logger: AstroIntegrationLogger;
      setFrontend: (args_0: { ...; }) => void;
    }) => void | Promise<void>;
    'studiocms:rendering': (params: {
      logger: AstroIntegrationLogger;
      setRendering: (args_0: { ...; }) => void;
    }) => void | Promise<void>;
    'studiocms:image-service': (params: {
      logger: AstroIntegrationLogger;
      setImageService: (args_0: { ...; }) => void;
    }) => void | Promise<void>;
    'studiocms:sitemap': (params: {
      logger: AstroIntegrationLogger;
      setSitemap: (args_0: { ...; }) => void;
    }) => void | Promise<void>;
  }
}

Definiendo un complemento

Para definir un complemento de StudioCMS, necesitas crear un objeto que cumpla con el tipo StudioCMSPlugin. Este objeto debería ser similar al siguiente, teniendo en cuenta que las siguientes propiedades son requeridas:

identifier: El identificador del complemento desde el archivo package.json.
name: El label del complemento para mostrar en el Dashboard de StudioCMS.
studiocmsMinimumVersion: La versión mínima de StudioCMS requerida para que el complemento funcione.

A continuación se muestra un ejemplo de definición de complemento de StudioCMS que incluye todas las propiedades requeridas así como una integración Astro para realizar lógica personalizada:

import { 
function definePlugin(options: StudioCMSPlugin): StudioCMSPlugin
Defines a plugin for StudioCMS.
@param ― options - The configuration options for the plugin.
@returns ― The plugin configuration.
definePlugin } from 'studiocms/plugins';
import { 
(alias) interface AstroIntegration
import AstroIntegration
AstroIntegration } from 'astro';

// Define las opciones para el complemento y la integración
interface 
interface Options
Options {
    
Options.foo: string
foo: string;
}

// Define la integración Astro
const 
const myIntegration: (options: Options) => AstroIntegration
myIntegration = (
options: Options
options: 
interface Options
Options): 
(alias) interface AstroIntegration
import AstroIntegration
AstroIntegration => ({
    
AstroIntegration.name: string
The name of the integration.
name: 'my-astro-integration',
    
AstroIntegration.hooks: {
    'astro:config:setup'?: (options: {
        config: AstroConfig;
        command: "dev" | "build" | "preview" | "sync";
        isRestart: boolean;
        updateConfig: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
        addRenderer: (renderer: AstroRenderer) => void;
        addWatchFile: (path: URL | string) => void;
        injectScript: (stage: InjectedScriptStage, content: string) => void;
        injectRoute: (injectRoute: InjectedRoute) => void;
        addClientDirective: (directive: ClientDirectiveConfig) => void;
        addDevToolbarApp: (entrypoint: DevToolbarAppEntry) => void;
        addMiddleware: (mid: AstroIntegrationMiddleware) => void;
        createCodegenDir: () => URL;
        logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    ... 10 more ...;
    'astro:routes:resolved'?: (options: {
        routes: IntegrationResolvedRoute[];
        logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
} & Partial<...>
The different hooks available to extend.
hooks: {
        "astro:config:setup": () => {
            
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log('Hello from my Astro Integration!');
        }
    }
});

// Define el complemento de StudioCMS
export const 
const myPlugin: (options: Options) => StudioCMSPlugin
myPlugin = (
options: Options
options: 
interface Options
Options) => 
function definePlugin(options: StudioCMSPlugin): StudioCMSPlugin
Defines a plugin for StudioCMS.
@param ― options - The configuration options for the plugin.
@returns ― The plugin configuration.
definePlugin({
    
StudioCMSPlugin.identifier: string
The identifier of the plugin, usually the package name.
identifier: 'my-plugin',
    
StudioCMSPlugin.name: string
The name of the plugin, displayed in the StudioCMS Dashboard.
name: 'My Plugin',
    
StudioCMSPlugin.studiocmsMinimumVersion: string
The minimum version of StudioCMS required for this plugin to function correctly.
This is used to ensure compatibility between the plugin and the StudioCMS core.
It should be a semantic version string (e.g., "1.0.0").
If the plugin is not compatible with the current version of StudioCMS, it should not be loaded.
This is a required field.
@example "1.0.0"
studiocmsMinimumVersion: '0.1.0',
    
StudioCMSPlugin.hooks: {
    'studiocms:astro-config'?: PluginHook<{
        logger: AstroIntegrationLogger;
        addIntegrations: (args_0: AstroIntegration | AstroIntegration[]) => void;
    }>;
    ... 5 more ...;
    'studiocms:sitemap'?: PluginHook<...>;
} & Partial<...>
hooks: {
      'studiocms:astro-config': ({ 
addIntegrations: (args_0: AstroIntegration | AstroIntegration[]) => void
addIntegrations }) => {
        
addIntegrations: (args_0: AstroIntegration | AstroIntegration[]) => void
addIntegrations(
const myIntegration: (options: Options) => AstroIntegration
myIntegration(
options: Options
options)) // Opcional, pero recomendado
      }
    }
});

En este ejemplo, definimos un complemento de StudioCMS llamado My Plugin que requiere la versión v0.1.0 o superior de StudioCMS. El complemento también proporciona una integración Astro que registra un mensaje en la consola cuando se llama al gancho astro:config:setup.

Para más información sobre cómo crear complementos, consulta el Haciendo complementos útiles Guide