tessl/npm-postcss-normalize-repeat-style

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

PostCSS Normalize Repeat Style

Name: tessl/npm-postcss-normalize-repeat-style
Author: tessl

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 Syntax	Output Syntax	Description
`repeat no-repeat`	`repeat-x`	Repeat horizontally only
`no-repeat repeat`	`repeat-y`	Repeat vertically only
`repeat repeat`	`repeat`	Repeat in both directions
`space space`	`space`	Space evenly in both directions
`round round`	`round`	Round spacing in both directions
`no-repeat no-repeat`	`no-repeat`	No 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

Install with Tessl CLI

npx tessl i tessl/npm-postcss-normalize-repeat-style

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 1 month ago
Describes: pkg:npm/postcss-normalize-repeat-style@7.0.x
Publish Source: CLI
Badge