The content of this section is derived from the content of the following links and is subject to the CC BY 4.0 license.
The following contents can be assumed to be the result of modifications and deletions based on the original contents if not specifically stated.
Rspack provides a set of JavaScript APIs to be used in JavaScript runtimes like Node.js or Bun.
The JavaScript API is useful in scenarios in which you need to customize the build or development process since all the reporting and error handling must be done manually and webpack only does the compiling part. For this reason the stats
configuration options will not have any effect in the rspack()
call.
@rspack/core
is designed based on Webpack's JavaScript API to ensure functional consistency and a similar user experience.
To start using the Rspack JavaScript API, first install @rspack/core
if you haven't yet:
Then require the @rspack/core
module in your JavaScript file:
The imported rspack function is fed a Rspack Configuration Object and runs the Rspack compiler if a callback function is provided:
The err
object will not include compilation errors. Those must be handled separately using stats.hasErrors()
, which will be covered in detail in the Error Handling section of this guide. The err
object will only contain rspack-related issues, such as misconfiguration, etc.
You can provide the rspack
function with an array of configurations. See the MultiCompiler section below for more information.
If you don't pass the rspack
runner function a callback, it will return a Rspack Compiler
instance. This instance can be used to manually trigger the Rspack runner or have it build and watch for changes, much like the CLI. The Compiler
instance provides the following methods:
.run(callback)
.watch(watchOptions, handler)
Typically, only one master Compiler
instance is created, although child compilers can be created in order to delegate specific tasks. The Compiler
is ultimately a function which performs bare minimum functionality to keep a lifecycle running. It delegates all the loading, bundling, and writing work to registered plugins.
The hooks
property on a Compiler
instance is used to register a plugin to any hook event in the Compiler
's lifecycle. The RspackOptionsApply
utilities are used by Rspack to configure its Compiler
instance with all the built-in plugins.
See Compiler API for more details.
The run
method is then used to kickstart all compilation work. Upon completion, the given callback
function is executed. The final logging of stats and errors should be done in this callback
function.
The API only supports a single concurrent compilation at a time. When using run
or watch
, call close
and wait for it to finish before calling run
or watch
again. Concurrent compilations will corrupt the output files.
Calling the watch
method triggers the rspack runner, but then watches for changes (much like CLI: rspack --watch
), as soon as Rspack detects a change, runs again. Returns an instance of Watching
.
Watching
options are covered in detail here.
Filesystem inaccuracies may trigger multiple builds for a single change. In the example above, the console.log
statement may fire multiple times for a single modification. Users should expect this behavior and may check stats.hash
to see if the file hash has actually changed.
See
Compiler.watch
for more details.
The stats
object that is passed as a second argument of the rspack()
callback, is a good source of information about the code compilation process. It includes:
The Rspack CLI uses this information to display nicely formatted output in your console.
When using the MultiCompiler
, a MultiStats
instance is returned that fulfills the same interface as stats
, i.e. the methods described below.
See Stats API for more details.
The MultiCompiler
module allows Rspack to run multiple configurations in separate compilers. If the options
parameter in the Rspack's JavaScript API is an array of options, Rspack applies separate compilers and calls the callback after all compilers have been executed.
See MultiCompiler API for more details.
For good error handling, you need to account for these three types of errors:
Here's an example that handles all conditions:
The current support for inputFileSystem
in Rspack is limited, and the ability to customize the filesystem read capability consistent with webpack has not yet been implemented. Please refer to: Issue #5091.
With Rspack, when using a specified output file system, there's no longer a requirement to supply mkdirp
and join
utility methods.
By default, Rspack reads files and writes files to disk using a normal file system. However, it is possible to change the input or output behavior using a different kind of file system (memory, webDAV, etc). To accomplish this, one can change the inputFileSystem
or outputFileSystem
. For example, you can replace the default outputFileSystem
with memfs
to write files to memory instead of to disk: