https://github.com/zachsa/esm-x
Enhance browser-JavaScript support to include JSX/Typescript syntax for websites utilizing importmaps.
https://github.com/zachsa/esm-x
importmaps
Last synced: 4 months ago
JSON representation
Enhance browser-JavaScript support to include JSX/Typescript syntax for websites utilizing importmaps.
- Host: GitHub
- URL: https://github.com/zachsa/esm-x
- Owner: zachsa
- License: mit
- Created: 2023-05-24T18:53:14.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-11-12T09:06:27.000Z (7 months ago)
- Last Synced: 2025-11-12T10:21:54.360Z (7 months ago)
- Topics: importmaps
- Language: JavaScript
- Homepage:
- Size: 4.94 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# esm-x
Enhance browser-JavaScript support to include JSX/Typescript syntax for websites utilizing importmaps.
- [Motivation](#motivation)
- [How it works](#how-it-works)
- [Usage](#usage)
- [Options](#options)
- [Importmaps](#importmaps)
- [External importmaps](#external-importmaps)
- [Local development](#local-development)
- [Publish](#publish)
- [Install](#install)
# Motivation
With all major browsers now supporting `importmaps`, bundle-free web development workflows have become both feasible and incredibly convenient. This project seeks to bring that convenience to React/Typescript projects.
## How it works
Leverages [importmaps](https://github.com/WICG/import-maps) in conjunction with [the ES Module Shim library](https://github.com/guybedford/es-module-shims). With `shimMode` forced to `true`, all Source Code from the website origin is transpiled using [Babel](https://babeljs.io/), while prior-optimized imports originating from a module CDN (such as the excellent JSPM CDN) are loaded directly.
# Usage
Include the `esm-x` library (328kB gzipped) as the first script in your HTML file, and include at least one `...`. Scripts of `type="esm-x"` will be transpiled and executed in the order they are included in the HTML page.
Here is an example of a simple React application with the `react` and `react-dom` library imports defined via an importmap. Copy this file into `index.html`, and serve via a web server (i.e. `npx http-server -c-1`). There is an example of an `@mui/material` app in [the dev directory of this repository](/dev/).
`esm-x` works without an importmap, but ES Module Shims is required.
```html
ESM-X Example
{
"imports": {
"react": "https://ga.jspm.io/npm:react@19.2.0/index.js",
"react-dom/client": "https://ga.jspm.io/npm:react-dom@19.2.0/client.js"
},
"scopes": {
"https://ga.jspm.io/": {
"react-dom": "https://ga.jspm.io/npm:react-dom@19.2.0/index.js",
"scheduler": "https://ga.jspm.io/npm:scheduler@0.27.0/index.js"
}
}
}
import React, { FC } from 'react';
import { createRoot } from 'react-dom/client';
const root = createRoot(document.getElementById('root') as HTMLElement);
const App: FC = () => <div>Hello from ESM-X</div>;
root.render(<App />);
```
## Options
Configure the ESM-X script by including HTML tag id and other attributes:
```html
```
## Importmaps
Head to the [JSPM generator](https://generator.jspm.io/) to quickly generate an importmap. Any importmap configuration should be supported - huge importmaps are fine, make sure to take advantage of dynamic imports / code splitting (for example, `Suspense/lazy` when using React), etc. (and obviously don't preload scripts)
### External importmaps
To use an external importmap, make sure that your importmap tag is of type "importmap-shim", and that the src url `endsWith('importmap') || endsWith('importmap.json')`. For example:
```html
```
It's easy to work with external importmaps using the [`jspm CLI`](https://jspm.org/docs/jspm-cli/stable/).
# Local development
Start a local web server and navigate to [localhost:3000/dev](http://localhost:3000/dev):
```sh
npx http-server --port 3000 -c-1
chomp --watch
```
Test the following cases:
- [index.html (default)](/dev/index.html)
- [no-importmap.html](/dev/no-importmap.html)
- [tsx.html](/dev/tsx.html)
- [empty-importmap.html](/dev/empty-importmap.html)
- [docs.html (copy this to README.md)](/dev/docs.html)
## Publish
```sh
npm publish --access public
```
# Install