livecodes/module-resolution

LiveCodes automatically resolves bare module imports to CDN URLs using import maps. Use npm packages and other modules without npm install or build steps.

Setup

import { createPlayground } from 'livecodes';

// Bare imports work automatically
createPlayground('#container', {
  config: {
    script: {
      language: 'javascript',
      content: `
import { v4 } from 'uuid';           // npm module
import React from 'react';            // npm module
import { useState } from 'react';     // Named import
console.log(v4());
      `,
    },
  },
});

Core Patterns

Import npm packages

// Default: uses esm.sh CDN
import { v4 } from 'uuid';
import React from 'react';
import { useState, useEffect } from 'react';
import { format } from 'date-fns';

// Specifying version
import React from 'react@18'; // React 18.x
import React from 'react@18.2.0'; // Exact version
import _ from 'lodash@4.17.21'; // Lodash specific version

Use different CDN providers

// esm.sh (default)
import React from 'react';
import React from 'esm.sh:react';

// Skypack
import React from 'skypack:react';

// jsDelivr
import React from 'jsdelivr:react';

// unpkg
import React from 'unpkg:react';

// Deno bundle
import { uuid } from 'deno:uuid';

// Full URL imports work too
import React from 'https://esm.sh/react@18';

Import from Deno, GitHub, JSR

// Deno.land/x (TS files auto-bundled)
import { uuid } from 'https://deno.land/x/uuid/mod.ts';

// JSR (Deno's npm-compatible registry)
import { yassify } from 'jsr:@kwhinnery/yassify';

// GitHub files (auto-bundled)
import { flatten } from 'https://github.com/remeda/remeda/blob/master/src/flatten.ts';

// Skip bundling with #nobundle
import { flatten } from 'https://github.com/remeda/remeda/blob/master/src/flatten.ts#nobundle';

// pkg.pr.new (unpublished packages)
import { Bench } from 'pr:tinybench@a832a55';

Custom import maps

// Via SDK config
createPlayground('#container', {
  config: {
    imports: {
      'my-lib': 'https://my-cdn.com/lib.js',
      'my-lib/utils': 'https://my-cdn.com/utils.js',
      'my-private-package': 'https://my-server.com/package/index.js',
    },
    script: {
      language: 'javascript',
      content: `
import { something } from 'my-lib';
import { helper } from 'my-lib/utils';
      `,
    },
  },
});

// Via custom settings in standalone app
// Settings → Custom Settings:
{
  "imports": {
    "my-lib": "https://my-cdn.com/lib.js"
  }
}

Change default CDN

const config = {
  customSettings: {
    defaultCDN: 'skypack', // Use Skypack for all bare imports
  },
  script: {
    language: 'javascript',
    content: `import React from 'react'; // Now uses skypack`,
  },
};

Import CSS from script

// URL ending in .css becomes <link>
import 'https://unpkg.com/github-markdown-css/github-markdown.css';

// Bare import for CSS
import 'github-markdown-css/github-markdown.css';
// Becomes: <link href="https://unpkg.com/github-markdown-css/github-markdown.css">

// Import compiled CSS from style editor
import styles from './style.css';
console.log(styles); // CSS string

Common Mistakes

HIGH Same module from different CDNs conflicts

Wrong:

// React from different CDNs are DIFFERENT instances
import React from 'esm.sh:react'; // React instance A
import { createRoot } from 'skypack:react-dom/client'; // React instance B
// BREAKS: createRoot expects React instance A

Correct:

// Always use same CDN (or no prefix = default)
import React from 'react';
import { createRoot } from 'react-dom/client';

// Or explicit same CDN
import React from 'esm.sh:react';
import { createRoot } from 'esm.sh:react-dom/client';

Module instances from different CDNs are separate. React context, hooks, and component state require the same instance.

Source: docs/docs/features/module-resolution.mdx — CDN Providers caution

MEDIUM CommonJS require works but ESM preferred

Works but not recommended:

const { v4 } = require('uuid'); // Works, converted to ESM
const React = require('react'); // Works

Preferred:

import { v4 } from 'uuid';
import React from 'react';

LiveCodes converts require to ESM imports, but explicit ESM is clearer and matches local development.

Source: docs/docs/features/module-resolution.mdx — CommonJS Modules section

LOW Not using #nobundle for pre-bundled URLs

When you want raw module URLs instead of bundling:

// Without #nobundle, this gets bundled by bundlejs.com
import { flatten } from 'https://github.com/remeda/remeda/blob/master/src/flatten.ts';

// With #nobundle, get the raw URL
import { flatten } from 'https://github.com/remeda/remeda/blob/master/src/flatten.ts#nobundle';

Use #nobundle when the URL already serves bundled code or when you want to avoid bundling overhead.

Source: docs/docs/features/module-resolution.mdx — GitHub/GitLab/Bitbucket section

CDN Provider Reference

Prefix	CDN	URL Format
(none)	esm.sh	https://esm.sh/{package}
esm.sh:	esm.sh	https://esm.sh/{package}
skypack:	Skypack	https://cdn.skypack.dev/{package}
jsdelivr:	jsDelivr	https://cdn.jsdelivr.net/npm/{package}
unpkg:	unpkg	https://unpkg.com/{package}?module
bundle:	bundlejs	https://deno.bundlejs.com/?file&q={package}
deno:	bundlejs	https://deno.bundlejs.com/?file&q={url}
jsr:	esm.sh (JSR)	https://esm.sh/jsr/{package}
pr:	esm.sh (pkg.pr.new)	https://esm.sh/pr/{package}

How It Works

1. Bare imports (import x from 'package') are resolved via import maps
2. Import map maps bare specifiers to full CDN URLs
3. CDN (default: esm.sh) serves ESM versions of npm packages
4. Deno/GitHub URLs ending in .ts/.tsx/.jsx are bundled via bundlejs.com
5. CommonJS require() calls are transpiled to ESM imports