Note: For settings related to individual Silex websites (found in the settings dialog), please consult the user docs.
This documentation covers Silex client and server configuration. To learn how to start Silex with a specific config file, please refer to this page.
In Silex, configuration files are also plugins. They are used to configure and customize the website builder's behavior. These configuration files fall into two categories: client-side and server-side.
Client-side Configuration: This type of configuration file is used to dictate the client-side behavior of Silex, including settings for the user interface, plugins, and other client-side features. It's written in JavaScript and is executed in the user's browser when they access Silex.
Server-side Configuration: This type of configuration file is used to control the server-side behavior of Silex. It can specify settings related to the server environment, such as the port number, database connection details, and server-side plugins. It's written in JavaScript and executed on the server when Silex starts.
In both configuration file types, you can use the config.addPlugin method to add plugins to Silex.
Here's an example of a Silex configuration file (this one you could use it on the client side or server side):
// client-config.js
// Start Silex with `silex --client-config /path/to/client-config.js`
import SomePlugin from 'some-plugin'
export default function(config, options) {
// Add a plugin
config.addPlugin(SomePlugin)
// Override default properties
config.debug = true
return {
debug: true, // This is another way to set properties of the config object
}
}
In order to use a configuration file, you need to start Silex with the command-line (CLI) and provide the path to the configuration file. For example:
npx @silexlabs/silex --client-config /path/to/client/config.js --config /path/to/server/config.js
In Silex, the configuration file also functions as an event emitter. This feature allows the configuration file to regulate the application's flow by emitting events at particular points, which plugins can listen for.
Here's an example of how to use this in a Silex configuration file or plugin:
export default function(config, options) {
config.on('silex:startup:end', function() {
// Do something when Silex has started
})
return {} // This will be merged into the config object
}
An instance of the ClientConfig class is passed to the initial config file which you provide in the command line argument or env var - check this page about running Silex with options. This is an essential class for configuring Silex or creating plugins.
The ClientConfig class extends the Config class from '@silexlabs/silex-plugins' and it sets up various aspects of the client-side configuration.
The ClientConfig class consists of the following properties:
| Property | Description |
|---|---|
debug |
A boolean value representing whether the application is in debug mode. |
lang |
The language for the I18n module. It gets its default value from the URL search parameters, or falls back to the DEFAULT_LANGUAGE constant. |
addHashInCssFileName |
Add hash in the file name of CSS at the time of publication. If true, CSS files of generated pages will look like page-name.123456.css instead of page-name.css. This is useful to avoid caching issues. Defaults to true. |
grapesJsConfig |
Configuration for the GrapesJS editor. |
clientConfigUrl |
The URL of the client config file, which is a plugin. |
getEditor() |
Retrieve GrapesJs editor. Only after the silex:startup:end or silex:grapesjs:end events. |
addSettings() and removeSettings() |
Add or remove a section in the page or site settings dialog. Check the docs about pages and website settings. For examples on how to use this, check the settings.ts file or the 11ty plugin for Silex |
// client-config.js
// Start Silex with `silex --client-config /path/to/client-config.js`
import blocksBasicPlugin from 'grapesjs-blocks-basic'
export default async function (config) {
config.grapesJsConfig.cssIcons = '/css/all.min.css'
config.grapesJsConfig.plugins.push((editor, opts) => { }) // Add any grapesjs plugin
}
Chekck GrapesJs docs for more about GrapesJs plugins and config
Silex Publication Transformers offer a powerful way to customize the site rendering and publication process of Silex. This is particularly useful for developers who host Silex for their users and want to tailor the output to match specific requirements, such as following a particular directory structure or file format, adjusting assets paths in the CSS or HTML, or fitting into a static site generator's conventions like Eleventy's.
To create a custom publication transformer, you can define a JavaScript object that implements the PublicationTransformer interface, then add it to the Silex config object with config.addPublicationTransformer().
Here's an example of how you might create a custom transformer in a config file or plugin:
export default async function (config) {
config.addPublicationTransformers({
transformPermalink(link: string, type: ClientSideFileType, initiator: Initiator): string {
switch(initiator) {
case Initiator.HTML:
// Add a cache buster
return `${link}?v=${Date.now()}}`
}
return link
},
transformFile(file) {
if(file.type === 'html') {
// HTML file transformation logic here
}
return {
...file,
content: 'TRANSFORMED FILE',
};
},
});
}
In this example, the renderComponent, renderCssRule, pageToSlug, and transformFile methods are placeholders. You should replace them with your own implementation to match your specific requirements.
Here are all the methods a transformer can have (check the source code):
export interface PublicationTransformer {
// Temporarily override how components render at publication by grapesjs
renderComponent?(component: Component, toHtml: () => string): string | undefined
// Temporarily override how styles render at publication by grapesjs
renderCssRule?(rule: CssRule, initialRule: () => ObjectStrings): ObjectStrings | undefined
// Transform files after they are rendered and before they are published
transformFile?(file: ClientSideFile): ClientSideFile
// Define files URLs
transformPermalink?(link: string, type: ClientSideFileType, initiator: Initiator): string
// Define where files are published
transformPath?(path: string, type: ClientSideFileType): string
}
Here are the possible values for type and initiator:
export enum ClientSideFileType {
HTML = 'html',
ASSET = 'asset',
CSS = 'css',
OTHER = 'other',
}
export enum Initiator {
HTML = 'html',
CSS = 'css',
}
And here are the default values:
export const publicationTransformerDefault: PublicationTransformer = {
// Override how components render at publication by grapesjs
renderComponent(component: Component, toHtml: () => string): string | undefined {
return toHtml()
},
// Override how styles render at publication by grapesjs
renderCssRule(rule: CssRule, initialRule: () => ObjectStrings): ObjectStrings | undefined {
return initialRule()
},
// Define where files are published
transformPath(path: string, type: ClientSideFileType): string {
return path
},
// Define links to files
transformPermalink(link: string, type: ClientSideFileType, initiator: Initiator): string {
switch(initiator) {
case Initiator.HTML:
return link
case Initiator.CSS:
// In case of a link from a CSS file, we need to go up one level
return `../${link.replace(/^\//, '')}`
default:
throw new Error(`Unknown initiator ${initiator}`)
}
},
// Define how files are named
transformFile(file: ClientSideFile): ClientSideFile {
return file
}
}
This documentation provides information about the ServerConfig class which is used for the server-side configuration of Silex. This class is instrumental when creating server-side plugins.
The ServerConfig class extends the Config class from '@silexlabs/silex-plugins' and configures various aspects of the server-side environment.
The ServerConfig class consists of the following properties:
An object containing various ExpressJS settings fetched from environment variables. These options include:
jsonLimit: limit for the maximum request body size when data is JSON. Default value is provided by the SILEX_EXPRESS_JSON_LIMIT environment variable.textLimit: limit for the maximum request body size when data is text. Default value is provided by the SILEX_EXPRESS_TEXT_LIMIT environment variable.urlencodedLimit: limit for the maximum request body size when data is URL-encoded. Default value is provided by the SILEX_EXPRESS_URLENCODED_LIMIT environment variable.sessionName: name for the session. Default value is provided by the SILEX_SESSION_NAME environment variable.sessionSecret: secret for the session. Default value is provided by the SILEX_SESSION_SECRET environment variable.cors: the Cross-Origin Resource Sharing (CORS) setting. Default value is provided by the SILEX_CORS_URL environment variable.The port on which the Silex server runs. Its value is set by the SILEX_PORT environment variable.
A Boolean property to enable or disable the debug mode. It is true if the SILEX_DEBUG environment variable is set to 'true'.
The URL where the Silex server is accessible. It's constructed using the SILEX_PROTOCOL, SILEX_HOST, and SILEX_PORT environment variables.
The path of the user's configuration file, fetched from the SILEX_CONFIG environment variable.
The path of the main configuration file. It is usually located at .silex.js in the root of the project.
The ServerConfig class also includes methods for configuring connectors and handling the configuration files. Read more about storage and hosting connectors
This method returns an array of all connectors (both storage and hosting), or only those of a specific type depending on the passed argument.
These methods are used to add a new storage connector to the list, set a new list of storage connectors, and retrieve the current list of storage connectors, respectively.
These methods are used to add a new hosting connector to the list, set a new list of hosting connectors, and retrieve the current list of hosting connectors, respectively.