npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ts-astroturf-tools

v0.16.0

Published

TypeScript tools that enhance astroturf.

Downloads

26

Readme

ts-astroturf-tools [beta! 🚧]

npm npm Build Status Coverage Status

This package improves DX for astroturf users.

Compatible with astroturf@>=1.0.0-beta, typescript@>=4 and webpack@>=5! For compatibility with astroturf@>=0.9 <= 1, use ts-astroturf-tools@<=0.14.3.

Installation

yarn add -D ts-astroturf-tools
npm i --save-dev ts-astroturf-tools

Overview

Features are divided in three major categories:

  • linaria-like functionality
  • diagnostic messages
  • autocomplete for identifiers

linaria-like functionality

  • Use variables declared in other modules inside your CSS:

    // * before
    // impossible :(
    
    // * after
    // colors.tsx
    export const RED = 'red';
    
    // index.tsx
    import { css } from 'astroturf';
    import { RED } from './colors';
    
    const btn = css`
      color: ${RED};
    `;
    
    // works for 'stylesheet' and ...
    import { stylesheet } from 'astroturf';
    
    const { a } = stylesheet`
      .a {
        color: ${RED};
      }
    `;
    
    // .. styled components too!
    import styled from 'astroturf/react';
    
    const Button = styled.button`
      color: ${RED};
    `;

Diagnostic messages

These messages are available if you use plain stylesheet tag from astroturf.

There are two types of diagnostic messages:

  • warnings in case there is unused CSS

    Available via:

    • webpack loader
    • babel plugin
    • TS Language Service Plugin (VS Code)
    import { stylesheet } from 'astroturf';
    
    const { btn } = stylesheet`
      .btn {
        color: red;
      }
      
      .active {
        color: green;
      }
    `;

    The warning will look like this:

    In VS Code the warning will become a suggestion:

  • errors in case there is missing CSS

    Available via:

    • webpack loader
    • babel plugin
    • TS Language Service Plugin (VS Code)
    import { stylesheet } from 'astroturf';
    
    const { btn, active } = stylesheet`
      .btn {
        color: red;
      }
    `;

    The error will look like this:

    In VS Code:

Autocomplete for identifiers

Available via:

  • TS Language Service Plugin (VS Code)

Quick summary of tools and their respective features

| Tool | Diagnostic messages | Autocomplete for identifiers | linaria-like functionality | | -------------------------- | ------------------- | ---------------------------- | ---------------------------- | | TS Language Service Plugin | ✅ | ✅ | N/A | | webpack loader | ✅ | N/A | ✅ optional | | babel plugin | ✅ | N/A | ❌ | | TS transformer | ❌ | N/A | ✅ |

  • N/A - not applicable

Configuration

  • TS Language Service Plugin

    Add ts-astroturf-tools as a plugin to your tsconfig.json:

    {
      "compilerOptions": {
        "plugins": [
          {
            "name": "ts-astroturf-tools"
          }
        ]
      },
      "files": ["src/index.tsx"],
      "exclude": ["node_modules"]
    }

    Don't forget to switch to workspace typescript instance:

  • TS transformer:

    • raw TypeScript

      You should use ttypescript as a compiler.

      Add ts-astroturf-tools/transformer as a transformer to your tsconfig.json:

      {
        "compilerOptions": {
          "plugins": [
            {
              "transform": "ts-astroturf-tools/transformer"
            }
          ]
        },
        "files": ["src/index.tsx"],
        "exclude": ["node_modules"]
      }
    • webpack / ts-loader

      const transformer = require('ts-astroturf-tools/transformer');
      
      module.exports = {
        // ...
        module: {
          // ...
          rules: [
            {
              test: /\.tsx$/,
              use: {
                loader: 'ts-loader',
                options: {
                  // ...
                  getCustomTransformers: () => ({
                    before: [transformer()],
                  }),
                },
              },
            },
          ],
        },
      };
  • webpack loader

    Add ts-astroturf-tools/loader as a first loader for ts-files:

    module.exports = {
      // ...
      module: {
        rules: [
          // ...
          {
            test: /\.tsx?$/,
            use: [
              // works with any typescript loader
              'ts-loader',
              'astroturf/loader',
              'ts-astroturf-tools/loader',
            ],
          },
        ],
      },
    };

    Available options:

    | Option name | Type | Description | | ----------- | --------- | ------------------------------------- | | linaria | boolean | Enables linaria-like functionality. |

    Defaults:

    module.exports = {
      // ...
      module: {
        rules: [
          // ...
          {
            test: /\.tsx?$/,
            use: [
              // works with any typescript loader
              'awesome-typescript-loader',
              'astroturf/loader',
              {
                loader: 'ts-astroturf-tools/loader',
                options: {
                  linaria: false,
                },
              },
            ],
          },
        ],
      },
    };
  • Babel plugin

    Add ts-astroturf-tools/babel-plugin to your babel plugins:

    module.exports = {
      presets: ['@babel/env', '@babel/preset-react'],
      plugins: ['ts-astroturf-tools/babel-plugin'],
    };

Known limitations

  • Regex-based parser is used to extract CSS class names.

  • Limited support for imports

    Supported extensions: .tsx, .ts, .js.

    Files must not contain side-effects, import other heavy modules and / or libraries and code that must be transpiled.

    This is ok:

    // a.js
    export const redColor = 'red';
    
    // b.js
    export const greenColor = 'green';
    export { redColor } from './a.js';
    
    // index.js
    import { greenColor, redColor } from './a.js';
    import styled from 'astroturf/react';
    
    const Button = styled.button`
      color: ${redColor};
      background: ${greenColor};
    `;

    This is not ok and will most likely result in an error:

    // a.js
    import * as React from 'react';
    import image from './someImage.png';
    export const redColor = 'red';
    
    export const Something = () => (
      <div style={{ background: `url(${image});` }}>Hello!</div>
    );
    
    // b.js
    export const greenColor = 'green';
    export { redColor } from './a.js';
    
    // index.js
    import { greenColor, redColor } from './a.js';
    import styled from 'astroturf/react';
    
    const Button = styled.button`
      color: ${redColor};
      background: ${greenColor};
    `;
  • Performance issues with imports (this issue is in progress of being fixed)

    As of now, files are parsed and executed for each encountered import.

    For example:

    // a.js
    export const RED = 'red';
    
    // b.js
    export { RED } from './a';
    export const GREEN = 'green';
    
    // ComponentA.js
    import styled from 'astroturf/react';
    import { GREEN } from './b';
    
    export const ComponentA = styled.div`
      color: ${GREEN};
    `;
    
    // ComponentB.js
    import styled from 'astroturf/react';
    import { RED } from './b';
    
    export const ComponentB = styled.div`
      color: ${RED};
    `;

    In this case both a.js and b.js will be parsed and executed twice (first for ComponentA.js and then for ComponentB.js). Keep this in mind and try to avoid creating large dependency trees.

  • Limited support for interpolations

    const WIDTH = '500px';
    
    // ok
    const { a } = stylesheet`
      .a {
        width: ${WIDTH};
      }
    `;
    const NAME = 'someClass';
    
    //        error
    //      vvvvvvvvv
    const { someClass } = stylesheet`
      .${NAME} {
        color: red;
      }
    `;
  • Only plain CSS is supported.

    Basic features of SASS/LESS/etc. may work:

    // simple nesting is ok
    const { someClass, anotherClass } = stylesheet`
      .someClass {
        color: red;
      
        &.anotherClass {
          border: 1px solid black;
        }
      }
    `;

    Advanced features will most probably not work:

    //                    error!
    //                 vvvvvvvvvvvv
    const { someClass, anotherClass } = stylesheet`
      @name: anotherClass;
      
      .someClass {
        color: red;
      
        &.@{name} {
          color: black;
        }
      }
    `;
  • It is not possible to show errors in case destructuring is not used:

    const classes = stylesheet`
      .a {
        color: red;
      }
    `;
    
    console.log(a.b); // <- no error

    This is not hugely important because you should always use css in the first place.