Now Playing Mathcore

    postcss-typed-css-classes

    0.2.5 • Public • Published

    PostCSS Typed Css Classes npm version

    PostCSS plugin that generates typed entities from CSS classes for a chosen programming language. You can also use it to filter CSS classes to reduce output size for faster application launch.

    Why

    I like atomic css libraries like TailwindCSS or Tachyons. I also like statically typed languages like Rust or Elm where compiler is your best friend and teacher.

    So this plugin is trying to solve these problems:

    1. How to force a compiler to check if used CSS class is valid (resp. given class exists in included stylesheet)?
    2. I don't remember all classes - autocomplete with a class description would be nice.
    3. How to reduce size of stylesheet?

    Solutions:

    1. Generate a file with source code in chosen language that mirrors your stylesheet and use it instead of plain string class names.
    2. Your IDE should autocomplete classes from generated file. You can use CSS attributes as a class description.
    3. Filter out classes from stylesheet that you didn't use. (Just search your source files for used classes.)

    Used In Projects:

    Do you use it? Create PR!

    Install

    yarn add postcss-typed-css-classes --dev

    Basic Usage

    postcss([
      require("postcss-typed-css-classes")({
        generator: "rust",
      }),
    ]);

    See Seed Quickstart Webpack for using with Webpack.

    See PostCSS docs for examples for your environment.

    Options

    • generator

      • can be:
        • a) name of a built-in generator
        • b) function with one parameter classes
          • it should return string
          • generated file will not be created when function doesn't return string
      • required
      • examples:
        • "rust"
        • function() {}
        • (classes) => `Classes: ${classes.length}`
      • classes example:
      [
        {
          "name": "container",
          "properties": [
            {
              "property": "max-width: 576px",
              "mediaQuery": "@media (min-width: 576px)"
            }
          ]
        }
      ]
    • output_filepath

      • a file path with filename and extension
      • generated code will be saved into this location
      • optional if generator does not provide a default otherwise it is required
      • examples:
        • path.resolve(__dirname, 'css_classes.rs')
    • purge

      • boolean to indicate that the output should be filtered
      • optional
      • default is false
    • content

      • Can be a path string pointing to the location of the files to be processed or an array of config objects
      • optional

      content options

      • path

        • a string path or an array of globs
        • optional if generator has specified a default otherwise required
      • regex

        • valid regex
        • optional if generator has specified a default otherwise required
      • mapper

        • map function
        • transforms class output
        • optional if generator has specified a default otherwise required
      • escape

        • boolean indicating that the output needs to be escaped to meet generator requirements
        • optional
        • default false

    examples

      require("postcss-typed-css-classes")({
        generator: "rust",
        content: 'src/**/*.rs'
      })
    
      require("postcss-typed-css-classes")({
        generator: "rust",
        purge: options.mode === "production",
        content: [
          { path: ['src/**/*.rs'] },
          {
            path: ['static/index.hbs', 'static/templates/**/*.hbs'],
            regex: /class\s*=\s*["'|][^"'|]+["'|]/g,
            mapper: className => {
              return (className.match(/class\s*=\s*["'|]([^"'|]+)["'|]/)[1]).match(/\S+/g)
            },
            escape: true
          }
        ],
      })
    
    • filter

      • a function with one parameter class_ that will be called when a CSS class is found in your stylesheet
      • optional
      • If a filter function is defined, it takes precedence over any of the content opts that may have been set
      • examples:
        • function() { return true }
        • (class_) => class_ !== "not-this-class"

    Contributing - How To Add A New Built-In Generator

    NOTE: Plugin is based on official postcss-plugin-boilerplate. So it uses old JS and very strict linter, but I think that code is clean enough and commented => it shouldn't be problem for a small project like this and we don't have to solve problems with building pipelines.

    1. Fork this repo
    2. Run yarn in project root
    3. Choose a name for a generator - we'll use csharp for this guide
    4. Duplicate file /generators/json_generator.js and rename it to csharp_generator.js
    5. Open csharp_generator.js and change:
    // - pretty-print JSON with 4 spaces indentation
    // - with a new line at the end of a file
    // - see EXAMPLE CODE:
    //     `/tests/json_generator_test/json_generator.basic.expected_output`
    function generate (classes) {
      return JSON.stringify(classes, undefined, 4) + os.EOL
    }

    to

    // - generate C# class
    // - see EXAMPLE CODE:
    //     `/tests/csharp_generator_test/csharp_generator.basic.expected_output`
    function generate (classes) {
      return "..I'm a c# class with " + classes.length + ' fields..' + os.EOL
    }
    1. Open /index.js
    2. Insert line
    var csharpGeneratorModule = require('./generators/csharp_generator')

    below the line

    var jsonGeneratorModule = require('./generators/json_generator')
    1. Insert case
    case 'csharp':
        return csharpGeneratorModule.generate

    into function getDefaultGenerator

    1. Duplicate folder /tests/json_generator_test and rename it to csharp_generator_test
    2. Rename /tests/csharp_generator_test/json_generator.basic.expected_output to csharp_generator.basic.expected_output
    3. Change content of csharp_generator.basic.expected_output to
    ..I'm a c# class with 6 fields..
    
    

    (new line at the end is necessary)

    1. Rename /tests/csharp_generator_test/json_generator.test.js to csharp_generator.test.js
    2. Open csharp_generator.test.js and change GENERATOR_NAME from json to csharp
    3. Run yarn test in the project root
    4. Update README.md if necessary
    5. Update CHANGELOG.md
    6. Create pull request to this repo (squash commits and rebase if necessary)

    Install

    npm i postcss-typed-css-classes

    DownloadsWeekly Downloads

    87

    Version

    0.2.5

    License

    MIT

    Unpacked Size

    44.9 kB

    Total Files

    30

    Last publish

    Collaborators

    • fattenap
    • martinkavik