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 🙏

© 2021 – Pkg Stats / Ryan Hefner

@magic-works/ttypescript-browser-like-import-transformer

v3.0.0

Published

A custom transformer that can be used with ttypescript to transform ts imports to browser style imports

Downloads

60

Readme

Jump to Install, Use cases, Motivation, or Documentation of options

Intro

This typescript transformer helps you to emit a browser compatible ESModule output. In general, it does two things:

  1. Add a ".js" after the local import
  2. Transform the node style dependencies (e.g. import React from "react") to
    1. A global variable access (const React = globalThis.React)
    2. A CDN (import _ from "https://cdn.skypack.dev/[email protected]")
    3. Another CDN (import _ from "https://unpkg.com/[email protected]?module")
    4. Snowpack style import (import _ from "/web_modules/lodash-es.js")
    5. [🧪Experimental] Read import rule from Import Map

Input

import './polyfill'
import * as React from 'react'

Output

const React = _import(globalThis["React"], [], "react", "globalThis.React", false);
import "./polyfill.js";
import { _import as _import } from "https://cdn.jsdelivr.net/npm/@magic-works/[email protected]/es/ttsclib.min.js";

Install

  1. Install typescript and ttypescript, and this transformer into your project if you don't already have them.

    npm install --save-dev typescript
    npm install --save-dev ttypescript
    npm install --save-dev @magic-works/ttypescript-browser-like-import-transformer
  2. You should use ESModule like target (es2015, esnext, etc) in your compiler options

    // tsconfig.json
    {
        "compilerOptions": {
            "module": "es2015",
            "plugins": [
                {
                    "transform": "@magic-works/ttypescript-browser-like-import-transformer",
                    "after": true
                    // Configs go here.
                }
            ]
        }
    }
  3. Write some typescript with normal imports

    import React from 'react'
  4. Compile using ttsc

    ttsc --project tsconfig.json

Use cases

Use with classic UMD dependencies

The default config of this transformer is "UMD" mode. All bare imports will be translated to a "UMD import". (e.g. import React from "react" becomes const React = globalThis.React). Then add a regular script tag to load React UMD.

Use with Webpack

Here is a template repo to help you use this transformer with Webpack. In this repo, all node style import is imported in a single file and packed by Webpack. The rest of the source code never gets handled by Webpack but emitted by ttypescript (an enhanced typescript cli that allows you to specify transformer programmatically).

Use with Snowpack

See the TTypeScript Support in the Importing Packages by Name section.

/* tsconfig.json */
{
    "compilerOptions": {
        "module": "es2015",
        "plugins": [
            {
                "transform": "@magic-works/ttypescript-browser-like-import-transformer",
                "after": true,
                "rules": "snowpack"
            }
        ]
    }
}

Use with CDN

Skypack CDN and unpkg are two CDNs that friendly to ES Module dependencies. This transformer also supports CDN import. (e.g. Before import _ from 'lodash-es' After import _ from 'https://cdn.skypack.dev/lodash-es')

/* tsconfig.json */
{
    "compilerOptions": {
        "module": "es2015",
        "plugins": [
            {
                "transform": "@magic-works/ttypescript-browser-like-import-transformer",
                "after": true,
                "rules": "skypack" // or "unpkg"
            }
        ]
    }
}

Motivation

Nowadays most of the codes in our codebase are ESModules. You can emit browser executable JS files by tsc directly but you have to add the annoying .js extension to the end. (Related: PR: New --emitExtension and --noImplicitExtensionName compiler options)

On the other hand, it is hard to run ES Module codes with Node style dependencies, there're some solutions to this including Snowpack but Snowpack also has its limits.

Options

See Options

Use programmatically

If you are using Node.js, import @magic-works/ttypescript-browser-like-import-transformer/cjs/node.js, it will export a ts.TransformerFactory<SourceFile>.

If you are in another environment or you want to modify the behavior of the transformer, use ./es/core.js and provide related I/O operations to create a ts.TransformerFactory<SourceFile>.

Once you get the ts.TransformerFactory<SourceFile>, you can use it like

const result = ts.transpileModule(source, {
    compilerOptions,
    transformers: {
        after: [
            transformer.default(
                {}, // Should be a Program but not used today.
                {
                    after: true,
                    // config here
                },
            ),
        ],
    },
})