or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-jss-preset-default

Default preset for JSS with selected plugins for comprehensive CSS-in-JS functionality

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/jss-preset-default@10.10.x

To install, run

npx @tessl/cli install tessl/npm-jss-preset-default@10.10.0

index.mddocs/

JSS Preset Default

JSS Preset Default provides a comprehensive, production-ready preset configuration for JSS (JavaScript Style Sheets) with 12 carefully selected plugins. It simplifies JSS setup by providing sensible defaults for common CSS-in-JS use cases while allowing customization of the most frequently configured options.

Package Information

  • Package Name: jss-preset-default
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install jss-preset-default

Core Imports

import preset from "jss-preset-default";

For CommonJS:

const preset = require("jss-preset-default");

Basic Usage

import jss from "jss";
import preset from "jss-preset-default";

// Basic setup with default configuration
jss.setup(preset());

// Create and use styles
const styles = jss.createStyleSheet({
  button: {
    fontSize: 16,        // Automatically becomes '16px'
    margin: [10, 20],    // Expands to '10px 20px'
    '&:hover': {         // Nested pseudo-selector
      backgroundColor: 'blue'
    }
  }
}).attach();

Architecture

JSS Preset Default is built around a curated collection of 12 JSS plugins that work together to provide comprehensive CSS-in-JS functionality:

  • Plugin Composition: Combines 12 complementary plugins in a specific order for optimal results
  • Sensible Defaults: Pre-configured plugins eliminate boilerplate setup for common use cases
  • Selective Configuration: Only the two most commonly customized plugins accept options
  • Type Safety: Full TypeScript support with complete type definitions

Capabilities

Preset Creation

Creates a JSS preset configuration object containing a plugins array with 12 pre-configured plugins for modern CSS-in-JS development.

/**
 * Creates a JSS preset configuration with 12 pre-configured plugins
 * @param options - Optional configuration for customizable plugins
 * @returns Object containing configured plugins array
 */
function preset(options?: Options): { plugins: ReadonlyArray<Plugin> };

interface Options {
  /** Configuration for default CSS units */
  defaultUnit?: DefaultUnitOptions;
  /** Configuration for observable rule values */
  observable?: ObservableOptions;
}

interface DefaultUnitOptions {
  /** Maps CSS property names to their default units */
  [key: string]: string;
}

interface ObservableOptions {
  /** Whether to process observable values */
  process?: boolean;
  /** Whether to force updates */
  force?: boolean;
}


interface Plugin {
  onCreateRule?(name: string, decl: JssStyle, options: RuleOptions): Rule;
  onProcessRule?(rule: Rule, sheet?: StyleSheet): void;
  onProcessStyle?(style: JssStyle, rule: Rule, sheet?: StyleSheet): JssStyle;
  onProcessSheet?(sheet?: StyleSheet): void;
  onChangeValue?(value: string, prop: string, rule: Rule): string | null | false;
  onUpdate?(data: object, rule: Rule, sheet?: StyleSheet): void;
}

Usage Examples:

import jss from "jss";
import preset from "jss-preset-default";

// Basic usage with defaults
jss.setup(preset());

// Customize default units
jss.setup(preset({
  defaultUnit: {
    'line-height': 'em',
    'font-size': 'rem',
    'margin': 'rem',
    'padding': 'rem'
  }
}));

// Configure observable options
jss.setup(preset({
  observable: {
    process: true,
    force: false
  }
}));

// Combine both configurations
jss.setup(preset({
  defaultUnit: {
    'font-size': 'rem'
  },
  observable: {
    process: true
  }
}));

Default Unit Configuration

Customizes automatic unit assignment for numeric CSS property values.

interface DefaultUnitOptions {
  /**
   * Maps CSS property names to their default units
   * When a numeric value is provided for these properties,
   * the specified unit will be automatically appended
   */
  [key: string]: string;
}

The plugin includes built-in defaults for common properties:

  • Most sizing properties (width, height, margin, padding, etc.) → px
  • Animation/transition durations → ms
  • Font-size related properties → px
  • Line-height → unitless (special handling)

Usage Examples:

// Override built-in defaults
const options = {
  defaultUnit: {
    'line-height': 'em',      // Instead of unitless
    'font-size': 'rem',       // Instead of 'px'
    'margin': 'rem',          // Instead of 'px'
    'padding': 'rem',         // Instead of 'px'
    'border-radius': 'em'     // Instead of 'px'
  }
};

// Now numeric values use custom units
const styles = {
  text: {
    fontSize: 1.2,      // Becomes '1.2rem'
    lineHeight: 1.5,    // Becomes '1.5em'
    margin: 16,         // Becomes '16rem'
    borderRadius: 0.5   // Becomes '0.5em'
  }
};

Observable Configuration

Configures reactive updates for observable rule values.

interface ObservableOptions {
  /** Whether to process observable values during updates */
  process?: boolean;
  /** Whether to force updates even when values haven't changed */
  force?: boolean;
}

Usage Examples:

import jss from "jss";
import preset from "jss-preset-default";
import { Observable } from "zen-observable";

// Configure observable behavior
jss.setup(preset({
  observable: {
    process: true,
    force: false
  }
}));

// Use observables in styles
const color$ = new Observable(observer => {
  observer.next('red');
  setTimeout(() => observer.next('blue'), 1000);
});

const styles = jss.createStyleSheet({
  button: {
    color: color$  // Automatically updates when observable emits
  }
}).attach();

Included Plugins

The preset includes these 12 plugins in the following order:

  1. jss-plugin-rule-value-function - Enables dynamic property values via functions
  2. jss-plugin-rule-value-observable - Enables reactive updates using observables
  3. jss-plugin-template - Support for template string styles
  4. jss-plugin-global - Support for global CSS rules using '@global'
  5. jss-plugin-extend - Rule extension and inheritance using 'extend' property
  6. jss-plugin-nested - Nested CSS selectors support ('&' syntax)
  7. jss-plugin-compose - Rule composition using 'composes' property
  8. jss-plugin-camel-case - Converts camelCase properties to kebab-case CSS
  9. jss-plugin-default-unit - Automatically adds units to numeric values
  10. jss-plugin-expand - Expands shorthand CSS properties
  11. jss-plugin-vendor-prefixer - Automatic vendor prefixing for CSS properties
  12. jss-plugin-props-sort - Consistent property order in output CSS

Feature Examples:

import jss from "jss";
import preset from "jss-preset-default";

jss.setup(preset());

const styles = jss.createStyleSheet({
  // Global styles
  '@global': {
    body: { margin: 0 }
  },
  
  // Main component with multiple features
  component: {
    // Default units (px added automatically)
    fontSize: 16,
    margin: [10, 20],
    
    // Camel case conversion
    backgroundColor: 'white',
    borderRadius: 4,
    
    // Property expansion
    padding: [10, 15, 10, 15],
    
    // Nested selectors
    '&:hover': {
      backgroundColor: 'gray'
    },
    
    // Function values
    color: () => Math.random() > 0.5 ? 'red' : 'blue',
    
    // Vendor prefixing (automatic)
    userSelect: 'none',
    transform: 'translateX(10px)'
  },
  
  // Rule extension
  extendedComponent: {
    extend: 'component',
    fontSize: 18
  }
}).attach();