To learn more about SSR - see this introduction post.
When creating your library / application you will see that you might need to make some changes to your project publish / consumption process in order to integrate Stylable to your SSR flow.
To integrate Stylable into your application, use
@stylable/webpack-plugin and configure it according to your project needs.
In order to use Stylable imports from your source files in
nodeJS, you will need to add
@stylable/node as a dependency.
Import and use its
requireHook method before rendering to enable requiring Stylable stylesheets in their
CommonJS module format.
In order to ensure full SSR compatibility, generated namespaces for all stylesheets must match exactly across all different build targets.
The default Stylable
namespaceResolver uses a combination of file-system path, name and version from the
package.json file to create its namespace. This means that namespaces can be influenced by the published file path structure.
If you choose to provide an alternative namespace resolver that does not depend on file paths as part of its namespace creation, then you can avoid the problem described below.
When building a library or application for consumption in both client and server environments it is common to output multiple transpilation targets for various module systems.
This means that a published project will usually have both
ES modules, each with their own transpiled copy of the project, including the Stylable assets.
This can pose a problem when trying to synchronize namespace creation for SSR.
Publishing SSR-ready source files (
The Stylable CLI offers a feature that allows you to sync your namespace across dist targets by inserting a custom header comment to the start of your
.st.css file. This header comment is used to normalize namespacing paths across different build targets.
@stylable/cli to publish your source stylesheets, use the
useNamespaceReference flag to mark all targets as originating from the same original source.
For this to work properly, your source folder must be published along with your distribution build targets.