Skip to main content
Scully provides two functions for accessing plugin configuration: getConfig for direct plugin references and getPluginConfig for retrieving config by plugin name.

​
getConfig

Retrieve configuration from a plugin function reference.

​
Signature

function getConfig<T>(plugin: PluginFunction): T

​
Parameters

​
plugin
PluginFunction
required
A reference to the plugin function (typically obtained via findPlugin).

​
Return Value

Returns the plugin’s configuration object. Returns an empty object {} if no configuration is set.

​
Usage

import { findPlugin, getConfig } from '@scullyio/scully';

const jsonPlugin = findPlugin('json', 'router');
const config = getConfig(jsonPlugin);

console.log(config);
// { url: 'https://api.example.com/products', limit: 100 }

​
getPluginConfig

Retrieve configuration by plugin name and optional type.

​
Signature

function getPluginConfig<T>(
  name: string | symbol,
  type?: PluginTypes
): T

​
Parameters

​
name
string | symbol
required
The unique identifier of the plugin.
​
type
PluginTypes
The plugin type. If omitted, searches all plugin types. Must be one of:
  • 'router'
  • 'render' or 'postProcessByHtml'
  • 'postProcessByDom'
  • 'fileHandler'
  • 'routeProcess'
  • 'allDone'
  • 'beforeAll'
  • 'routeDiscoveryDone'
  • 'enterprise'
  • 'scullySystem'

​
Return Value

Returns the plugin’s configuration object with type T. Returns an empty object if no configuration is set.

​
Usage

import { getPluginConfig } from '@scullyio/scully';

interface JsonPluginConfig {
  url: string;
  limit?: number;
}

const config = getPluginConfig<JsonPluginConfig>('json', 'router');
console.log(config.url); // Type-safe access

​
Setting Plugin Configuration

​
setPluginConfig

Set configuration for a plugin by name. 
import { setPluginConfig } from '@scullyio/scully';

// Set config for a specific plugin type
setPluginConfig('json', 'router', {
  url: 'https://api.example.com/products',
  limit: 100
});

// Set config without specifying type (searches all types)
setPluginConfig('customRender', {
  theme: 'dark',
  syntaxHighlight: true
});

​
setConfig

Set configuration using a direct plugin reference. 
import { findPlugin, setConfig } from '@scullyio/scully';

const plugin = findPlugin('json', 'router');
setConfig(plugin, {
  url: 'https://api.example.com/products',
  limit: 100
});

​
Configuring Plugins in scully.config.ts

The most common way to configure plugins is through scully.config.ts: 
import { ScullyConfig, setPluginConfig } from '@scullyio/scully';

// Configure a router plugin
setPluginConfig('json', 'router', {
  url: 'https://api.example.com/products'
});

// Configure a render plugin
setPluginConfig('critical-css', 'postProcessByHtml', {
  inlineImages: false,
  minify: true
});

export const config: ScullyConfig = {
  projectRoot: './src',
  projectName: 'my-app',
  outDir: './dist/static',
  routes: {
    '/products/:id': {
      type: 'json',
      url: 'https://api.example.com/products'
    }
  }
};

​
Route-Specific Configuration

You can also configure plugins per route using the route configuration: 
import { ScullyConfig } from '@scullyio/scully';

export const config: ScullyConfig = {
  projectRoot: './src',
  projectName: 'my-app',
  outDir: './dist/static',
  routes: {
    '/blog/:slug': {
      type: 'contentFolder',
      slug: {
        folder: './blog'
      },
      // Route-specific plugin config
      postRenderers: ['customRender'],
    }
  }
};

​
Accessing Configuration in Plugins

Within your plugin implementation, access configuration using getConfig: 
import { registerPlugin, RoutePlugin, getConfig } from '@scullyio/scully';

interface JsonPluginConfig {
  url: string;
  limit?: number;
  headers?: Record<string, string>;
}

const jsonPlugin: RoutePlugin = async function(route, config) {
  // Get the plugin's configuration
  const pluginConfig = getConfig<JsonPluginConfig>(jsonPlugin);
  
  // Merge with route-specific config
  const finalConfig = { ...pluginConfig, ...config };
  
  const response = await fetch(finalConfig.url, {
    headers: finalConfig.headers || {}
  });
  
  const data = await response.json();
  const limit = finalConfig.limit || data.length;
  
  return data.slice(0, limit).map(item => ({
    route: `/products/${item.id}`,
    type: 'json',
    data: item
  }));
};

registerPlugin('router', 'json', jsonPlugin);

​
Type Safety

Use TypeScript interfaces for type-safe configuration access: 
import { getPluginConfig } from '@scullyio/scully';

// Define your config interface
interface MyPluginConfig {
  apiKey: string;
  endpoint: string;
  retries?: number;
}

// Get config with type safety
const config = getPluginConfig<MyPluginConfig>('myPlugin', 'router');

// TypeScript will enforce types
const apiKey: string = config.apiKey; // OK
const invalid: number = config.apiKey; // Error: Type 'string' is not assignable to type 'number'

​
Configuration Backup and Reset

Scully internally maintains a backup of plugin configurations. This is primarily used for route-specific configuration: 
import { findPlugin } from '@scullyio/scully';

const plugin = findPlugin('myPlugin', 'router');

// Access backup configuration (internal use)
const backup = plugin['___Scully_config_for_plugin___BackupData__'];

// Reset to backup configuration (internal use)
if (plugin['___Scully_config_for_plugin___resetData__']) {
  plugin['___Scully_config_for_plugin___resetData__']();
}
The backup and reset mechanisms are intended for internal use by Scully’s routing system. Avoid manipulating these directly in your plugins.

​
Best Practices

Always define interfaces for your plugin configuration:
interface MyPluginConfig {
  required: string;
  optional?: number;
}

const config = getPluginConfig<MyPluginConfig>('myPlugin');
Check for configuration values and provide defaults:
const config = getConfig<MyPluginConfig>(plugin);
const retries = config.retries ?? 3;
const timeout = config.timeout ?? 5000;
Use config validators when registering router plugins:
const validator = (config) => {
  const errors = [];
  if (!config.url) {
    errors.push('url is required');
  }
  if (config.limit && config.limit < 1) {
    errors.push('limit must be positive');
  }
  return errors;
};

registerPlugin('router', 'json', jsonPlugin, validator);
Plugin configuration is passed to Puppeteer, so it must be serializable:
// Good: Serializable config
setPluginConfig('myPlugin', {
  url: 'https://api.example.com',
  timeout: 5000,
  headers: { 'Authorization': 'Bearer token' }
});

// Bad: Contains functions (not serializable)
setPluginConfig('myPlugin', {
  transform: (data) => data.toUpperCase() // Error!
});

​
Source Reference

  • getConfig: libs/scully/src/lib/pluginManagement/pluginConfig.ts:82
  • getPluginConfig: libs/scully/src/lib/pluginManagement/pluginConfig.ts:38
  • setConfig: libs/scully/src/lib/pluginManagement/pluginConfig.ts:87
  • setPluginConfig: libs/scully/src/lib/pluginManagement/pluginConfig.ts:22

registerPlugin

Register plugins with configuration validators

findPlugin

Find plugins to access their configuration

ScullyConfig

Learn about Scully’s main configuration

Route Config

Configure individual routes

Build docs developers (and LLMs) love

Get started for freeTalk to us