or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-postcss-normalize-repeat-style

PostCSS plugin that converts two-value background-repeat and mask-repeat syntax into single-value shorthand equivalents.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/postcss-normalize-repeat-style@7.0.x

To install, run

npx @tessl/cli install tessl/npm-postcss-normalize-repeat-style@7.0.0

index.mddocs/

PostCSS Normalize Repeat Style

PostCSS Normalize Repeat Style is a PostCSS plugin that optimizes CSS by converting two-value background-repeat and mask-repeat syntax into single-value shorthand equivalents. This plugin reduces CSS file size while maintaining identical visual behavior, making it ideal for CSS optimization pipelines and build tools.

Package Information

  • Package Name: postcss-normalize-repeat-style
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install postcss-normalize-repeat-style

Core Imports

const normalizeRepeatStyle = require("postcss-normalize-repeat-style");

For ES modules:

import normalizeRepeatStyle from "postcss-normalize-repeat-style";

Basic Usage

const postcss = require("postcss");
const normalizeRepeatStyle = require("postcss-normalize-repeat-style");

const css = `
  .element {
    background: url(image.jpg) repeat no-repeat;
    mask-repeat: no-repeat repeat;
  }
`;

const result = postcss([normalizeRepeatStyle()])
  .process(css, { from: undefined });

console.log(result.css);
// Output:
// .element {
//   background: url(image.jpg) repeat-x;
//   mask-repeat: repeat-y;
// }

Capabilities

Plugin Creator Function

Creates a PostCSS plugin instance that normalizes repeat-style values in CSS declarations.

/**
 * Creates a PostCSS plugin that normalizes background-repeat and mask-repeat values
 * @returns {import('postcss').Plugin} PostCSS plugin instance
 */
function normalizeRepeatStyle(): import('postcss').Plugin;

The plugin automatically processes the following CSS properties:

  • background (when containing repeat values)
  • background-repeat
  • mask-repeat (including vendor-prefixed variants like -webkit-mask-repeat)

Plugin Properties

The plugin creator function includes a PostCSS marker property:

normalizeRepeatStyle.postcss = true;

Transformation Rules

The plugin applies the following transformations to repeat values:

Input SyntaxOutput SyntaxDescription
repeat no-repeatrepeat-xRepeat horizontally only
no-repeat repeatrepeat-yRepeat vertically only
repeat repeatrepeatRepeat in both directions
space spacespaceSpace evenly in both directions
round roundroundRound spacing in both directions
no-repeat no-repeatno-repeatNo repetition in either direction

Advanced Features

CSS Variable Preservation

The plugin intelligently preserves CSS custom properties and variable functions to avoid breaking dynamic values:

/* These remain unchanged */
.element {
  background-repeat: var(--custom-repeat);
  background: url(image.jpg) env(--repeat-value);
  mask-repeat: constant(--mask-repeat);
}

Preserved variable functions:

  • var() - CSS custom properties
  • env() - Environment variables
  • constant() - Legacy environment variables

Multiple Background Support

The plugin correctly handles multiple background layers separated by commas:

/* Input */
.element {
  background: 
    url(bg1.jpg) repeat no-repeat,
    url(bg2.jpg) no-repeat repeat;
}

/* Output */
.element {
  background: 
    url(bg1.jpg) repeat-x,
    url(bg2.jpg) repeat-y;
}

Background Size Preservation

The plugin avoids processing values after the background-size separator (/) to prevent incorrect transformations:

/* Input - size values after '/' are preserved */
.element {
  background: url(image.jpg) repeat no-repeat / 100px 50px;
}

/* Output */
.element {
  background: url(image.jpg) repeat-x / 100px 50px;
}

Performance Optimization

The plugin includes built-in caching to avoid redundant processing of identical values, improving build performance for large stylesheets.

Usage Examples

PostCSS Configuration

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-normalize-repeat-style'),
    // other plugins...
  ]
};

Gulp Integration

const gulp = require('gulp');
const postcss = require('gulp-postcss');
const normalizeRepeatStyle = require('postcss-normalize-repeat-style');

gulp.task('css', () => {
  return gulp.src('src/**/*.css')
    .pipe(postcss([
      normalizeRepeatStyle(),
    ]))
    .pipe(gulp.dest('dist'));
});

Webpack Integration

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [
                  require('postcss-normalize-repeat-style'),
                ],
              },
            },
          },
        ],
      },
    ],
  },
};

Dependencies

Runtime Dependencies

// postcss-value-parser: ^4.2.0
// Used for parsing and manipulating CSS values

Peer Dependencies

// postcss: ^8.4.31
// The PostCSS processor framework

Types

// TypeScript definitions available at types/index.d.ts
interface PluginCreator {
  (): import('postcss').Plugin;
  postcss: true;
}

// Plugin returns standard PostCSS Plugin interface
// postcss.Plugin interface includes:
// - postcssPlugin: string (plugin name identifier)
// - prepare(): object with processor methods like OnceExit