Skip to main content

Programmatic API

Stylable instance

Stylable is usually consumed through one of its available integration, for more specific or advanced use-cases, the programmatic API can be used for greater control on how Stylable operates.

note

The APIs described here are treated as stable, and available for use. Any other API exposed by Stylable not described here may changed, and should not be dependant on.

The Stylable class provided from @stylable/core requires configuration to initialize.

Example:

Initialize Stylable instance
import fs from 'node:fs';
import { Stylable } from '@stylable/core';

// minimal required configuration
Stylable({ fs, projectRoot: __dirname });

Configuration

OptionTypeDefault ValueDescription
fsMinimalFSrequiredFilesystem instance to use
projectRootstringrequiredThe project root directory path
modestring"production"Development or production mode
resolveNamespaceResolveNamespacedefault resolver depends on running contextFunction to determine namespacing
resolveModuleModuleResolverenhanced-resolveModule resolver to be used for all import paths and url() requests
resolveOptions
{
alias?: any;
symlinks?: boolean;
}
{}
Options that are passed to the default module resolver
requrieModuleRequireModulenoneRequire module that receives a path, and attempts to return a module

MinimalFS

Stylable minimal required file system interface:

MinimalFS interface
interface MinimalFS {
statSync: (filePath: string) => { mtime: Date };
readFileSync: (filePath: string, encoding: 'utf8') => string;
readlinkSync: (filePath: string) => string;
}

ResolveNamespace

Provide exact control of the namespacing mechanism by providing a function that accepts:

  • namespace - a stylesheet source namespace - determined by the @st-namespace if exists, and falls back to the filename
  • origin - an origin path - path to the source stylesheet

This function will then return a string to be used as the "namespace" for stylesheet definitions.

Basic example

An example for a basic namespace resolver, that generates unique verbose namespaces based on the component namespace and origin path of the stylesheet.

Resolve namespace example
const resolveNamespace: ResolveNamespace = (namespace: string, origin: string): string {
return namespace + hash(origin);
}
comp.st.css
.root {}

/* OUTPUT */
.comp1169059893__root {}

ModuleResolver

Override Stylable's default module resolver, to control path resolution according to your projects' needs.

The default module resolver is a function that accepts two arguments:

  • directoryPath - the directory path to resolve from
  • request - the module request to resolve
const fs = require('node:fs');
const { createDefaultResolver, Stylable } = require('@stylable/core');

const defaultResolver = createDefaultResolver(fs);
const stylable = new Stylable({
projectRoot: 'path/to/project/root',
filesystem: fs,
resolveModule: (directoryPath, request) => {
if (request.startsWith('my-custom-module')) {
return '/path/to/my-custom-module';
}

return defaultResolver(directoryPath, request);
},
});

RequireModule

Defines a function to require imported JavaScript modules from a path, used when a JavaScript Mixins or Formatters is used within a Stylable stylesheet.

const fs = require('node:fs');
const { Stylable } = require('@stylable/core');

const stylable = new Stylable({
projectRoot: 'path/to/project/root',
filesystem: fs,
requireModule: require
})