Configuration
It loads the first config it finds in the following order:
config/rocket.config.js
config/rocket.config.mjs
config/rocket.config.js
rocket.config.mjs
It typically looks something like this
import { rocketLaunch } from '@rocket/launch';
import { absoluteBaseUrlNetlify } from '@rocket/netlify';
export default /** @type {import('@rocket/cli').RocketCliOptions} */ ({
presets: [rocketLaunch()],
absoluteBaseUrl: absoluteBaseUrlNetlify('http://localhost:8080'),
});
tip
The configuration should only be used to define global settings that can NOT be overridden within a page. For settings that may be overridden within a page, use the data cascade feature.
Rocket is primarily built around plugins for each of its systems.
Given that rocket comes with a list of default plugins and that presets can add plugins it's very important to not "just" set a new "plugins" property.
To enable customization we make use of the plugins-manager.
New plugins can be added and all default plugins can be adjusted or even removed by using the following functions.
/** @type {import('rocket/cli').RocketCliConfig} */
export default {
// add a rollup plugin to the web dev server (will be wrapped with @web/dev-server-rollup) AND the rollup build (e.g. enable json importing)
setupDevServerAndBuildPlugins: [],
// add a plugin to the web dev server (will not be wrapped) (e.g. esbuild for TypeScript)
setupDevServerPlugins: [],
// add a middleware to the web dev server (e.g. api proxy)
setupDevServerMiddleware: [],
// add a plugin to the rollup build (e.g. optimization steps)
setupBuildPlugins: [],
// add a plugin to the cli (e.g. a new command like "rocket my-command")
setupCliPlugins: [],
};
Adjusting the input/output directories
Rocket comes with sensible defaults for the input and output directories you can however override those if needed.
You can either set a URL or an absolute path.
tip
Using new URL('./path/to/dir', import.meta.url)
makes sure that the path is relative to the current file.
Here is an example where we use a deeper folder for the pages and output to a root dist
folder.
👉 config/rocket.config.js
export default {
inputDir: new URL('../projectX/site/pages', import.meta.url),
outputDir: new URL('../dist', import.meta.url),
};
Adding an API proxy
If we want to access an API client side we need to access it via the same domain. However in most cases the API server is running on a different server/url/domain.
Doing cross domain/port request is not allowed on the client side. To still access it we can use a proxy.
Let's say we have an API server running on port 9000 and the Rocket Dev Server is run on port 8000.
import proxy from 'koa-proxy';
import { addPlugin } from 'plugins-manager';
export default /** @type {import('rocket/cli').RocketCliConfig} */ ({
setupDevServerMiddleware: [
addPlugin(proxy, {
host: 'http://localhost:9000/',
match: /^\/api\//,
}),
],
});
We can now do ajax requests to http://localhost:8000/api/message
and it will be proxied to http://localhost:9000/api/message
.
Adding Rollup Plugins
For some projects you might want to enable non-standard behaviors like importing JSON files as JavaScript.
import data from './data.json';
You can accomplish this with Rollup and dev server plugins. Make sure to add both the dev-server plugin as well as the Rollup plugin, so that the behavior is the same during development as it is in the production build.
For these cases you can use setupDevServerAndBuildPlugins
, which will automatically add the plugin for you to both Rollup and dev-server:
import json from '@rollup/plugin-json';
import { addPlugin } from 'plugins-manager';
/** @type {import('@rocket/cli').RocketCliOptions} */
export default {
setupDevServerAndBuildPlugins: [addPlugin(json, { my: 'settings' }, { location: 'top' })],
};
This will add the Rollup plugin json
with the id json
at the top of the plugin list of Rollup and the dev server. It needs to be at the top so further plugins down the line can work with JSON imports.
For the Dev Server the plugins are automatically wrapped by @web/dev-server-rollup
. Note that not all Rollup plugins will work with the dev-server.
Modifying Options of Plugins
All plugins which are either default or are added via a preset can still be adjusted by using adjustPluginOptions
.
import { adjustPluginOptions } from 'plugins-manager';
/** @type {import('@rocket/cli').RocketCliOptions} */
export default {
setupDevServerAndBuildPlugins: [adjustPluginOptions(json, { my: 'overwrite settings' })],
};
Advanced
Sometimes you need even more control over specific settings.
DevServerOptions (@web/dev-server)
export default /** @type {import('rocket/cli').RocketCliOptions} */ ({
adjustDevServerOptions: options => ({
...options,
hostname: 'my-hostname',
}),
});
BuildOptions (rollup)
For example if you wanna add an acorn
plugin to rollup
import { importAssertions } from 'acorn-import-assertions';
export default /** @type {import('rocket/cli').RocketCliOptions} */ ({
adjustBuildOptions: options => ({
...options,
acornInjectPlugins: [importAssertions],
}),
});