Configuration API
The zuby.config.mjs
config file is a file that contains all the configuration options for your Zuby.js app.
The typescript projects use zuby.config.ts
instead.
A valid config file exports its configuration using the default export
and defineConfig
function that provides type checking and autocompletion for the config file.
Here’s the example of a simple config file for a Zuby.js app with Preact. See the config options section for more details.
Custom config file name
You can use a custom config file name by passing the --config-file
option to the CLI:
ZubyConfig API
The section describes all available configuration options for Zuby.js
on ZubyConfig
type.
jsx
This option is set to JSX provider which will be used to render the pages.
- Type:
JsxProvider
- See the JsxProvider API for more details. - Example:
preact()
,react()
- Required:
true
srcDir
This option defines the path to directory where your zuby project is located in.
- Type:
string
- Default:
./
outDir
This option defines the directory where the build output will be placed relative to project root.
- Type:
string
- Default:
.zuby
publicDir
This option defines the relative path to the folder with the static files. These files are copied to the output directory.
- Type:
string
- Default:
public/
cacheDir
This option defines the relative path to directory where the cache will be stored.
- Type:
string
- Default:
.zuby-cache
output
The build mode. This config option allows you to change whether the pages should be pre-rerendered by default or not. Possible values are ‘static’ or ‘server’.
- ‘static’ - Opt-out mode - When set to ‘static’, all pages with static paths will be pre-rendered to HTML files by default unless the page exports the
prerender
property with false value. - ‘server’ - Opt-in mode - When set to ‘server’, the pages will be pre-rendered to HTML files
only when the page exports the
prerender
property with true value. - Type:
'static' | 'server'
- Default:
static
prerenderPaths
List of additional paths to pre-render during the build. The static paths are pre-rendered automatically in static
build mode and don’t need to be specified here.
- Type:
string[]
- Default:
[]
- Example:
['/about', '/contact', '/products/123']
site
The URL of the site.
- Type:
string
- Default:
undefined
- Example:
https://example.com
i18n
The internalization config. If this is set, the site will be generated in multiple locales.
- Type:
{ locales: string[]; defaultLocale: string; }
- Default:
undefined
minifyHTML
Set this option to false to disable the minification of pre-rendered HTML.
- Type:
boolean
- Default:
true
minifyCSS
Set this option to false to disable the minification of CSS.
- Type:
boolean
- Default:
true
minifyJS
Set this option to false to disable the minification of JS.
- Type:
boolean
- Default:
true
plugins
The list of plugins that use either the Zuby plugin API or Vite plugin API. See the ZubyPlugin or Vite Plugin API section for more details.
- Type:
(ZubyPlugin | VitePluginOption)[];
- Default:
[]
server
Server options for both the dev and production server. It has two properties:
host
: The host to listen on. Set this option to ‘0.0.0.0’ to listen on all interfaces. This config option can be overwritten by the--host
CLI argument.- Type:
string
- Default:
127.0.0.1
- Type:
port
: The port to listen on. This config option can be overwritten by the--port
CLI argument. NOTE: Keep in mind that ports below 1024 are usually reserved for root users.- Type:
number
- Default:
3000
- Type:
logLevel
The log level for both Zuby and all plugins.
- Type:
'error' | 'warn' | 'info' | 'silent'
- Default:
info
customLogger
The custom logger for both Zuby, Vite and all plugins.
- Type:
ZubyLogger
- Default:
ZubyLogger
generateBuildId
The custom build ID generator. This function is called during the build process. If you’re building in multiple environments, you can use this option to generate consistent build IDs.
- Type:
() => string | Promise<string>
- Default:
generateDefaultBuildId
image
The image component options:
loader
: The path to image loader to use. The image loader function that generates the URL for the<Image>
component.- Type:
string
- Default:
zuby/image/imageLoader.js
- Type:
sizes
: The array of image sizes that will be used to generate image src. Zuby.js will try to use the nearest size to the actual specified size.- Type:
number[]
- Default:
[160, 320, 640, 768, 1024, 1280, 1536, 1920, 2048]
- Type:
defaultFormat
: The default format of the image, that will be passed to the image loader function if the format is not specified.- Type:
'webp' | 'jpg' | 'jpeg' | 'png' | 'avif' | 'gif'
- Default:
'webp'
- Type:
defaultQuality
: The default quality of the image, that will be passed to the image loader function if the quality is not specified.- Type:
number
- Default:
80
- Type:
props
The global props for the site that will be passed to all pages, handlers etc… on both client and server side.
They can be retrieved using PageContext.globalProps
method.
- Type:
Record<string, any>
- Default:
{}
serverProps
The global server props for the site that will be passed to all pages, handlers etc… only on server side.
They can be retrieved using PageContext.globalServerProps
method.
- Type:
Record<string, any>
- Default:
{}
vite
The additional vite config, which will be merged with the default config.
See the Vite config docs and build options for all available options.
- Type:
ViteUserConfig
- Default:
{}