devjar 0.2.2 → 0.3.1

package/README.md

@@ -4,15 +4,68 @@
 
 ![image](https://repository-images.githubusercontent.com/483779830/28347c03-774a-4766-b113-54041fad1e72)
 
+### Introduction
+
+devjar is a library that enables you to live test and share your code snippets and examples with others. devjar will generate a live code editor where you can run your code snippets and view the results in real-time based on the provided code content of your React app. 
+
+Notice: devjar only works for browser runtime at the moment. It will always render the default export component in `index.js` as the app entry.
+
 ### Install
 
 ```sh
 yarn add devjar
 ```
 
+
 ### Usage
 
-```js
+#### `<DevJar>`
+
+`DevJar` is a react component that allows you to develop and test your code directly in the browser, using a CDN to load your dependencies.
+
+**Props**
+
+* `files`: An object that specifies the files you want to include in your development environment.
+* `getModuleUrl`: A function that maps module names to CDN URLs.
+* `onError`: Callback function of error event from the iframe sandbox. By default `console.log`.
+
+
+```jsx
+import { DevJar } from 'devjar'
+
+const CDN_HOST = 'https://esm.sh'
+
+const files = {
+  'index.js': `export default function App() { return 'hello world' }`
+}
+
+function App() {
+  return (
+    <DevJar
+      files={files}
+      getModuleUrl={(m) => {
+        return `${CDN_HOST}/${m}`
+      }}
+    />
+  )
+}
+```
+
+#### `useLiveCode(options)`
+
+**Parameters**
+
+* `options`
+  * `getModulePath(module)`: A function that receives the module name and returns the CDN url of each imported module path. For example, import React from 'react' will load React from skypack.dev/react.
+
+**Returns**
+
+* `state`
+  * `ref`: A reference to the iframe element where the live coding will be executed.
+  * `error`: An error message in case the live coding encounters an issue.
+  * `load(codeFiles)`: void: Loads code files and executes them as live code.
+
+```jsx
 import { useLiveCode } from 'devjar'
 
 function Playground() {

package/lib/core.mjs

@@ -1,46 +1,202 @@
-async function createModule(files, { getModulePath }) {
-  let currentImportMap
-  let shim
-
-  async function setupImportMap() {
-    if (shim) return shim
-    window.esmsInitOptions = {
-      shimMode: true,
-      mapOverrides: true,
-    }
-    shim = import(/* webpackIgnore: true */ getModulePath('es-module-shims'))
-    await shim
-  }
+import { useEffect, useCallback, useState, useId, useRef } from 'react'
+import { createModule } from './module.mjs'
+import { transform } from 'sucrase'
+import { init, parse } from 'es-module-lexer'
+
+let esModuleLexerInit
+
+const isRelative = s => s.startsWith('./')
+
+function transformCode(_code, getModuleUrl, externals) {
+  const code = transform(_code, {
+    transforms: ['jsx', 'typescript'],
+  }).code
+
+  return replaceImports(code, getModuleUrl, externals)
+}
+
+function replaceImports(_code, getModuleUrl, externals) {
+  let code = ''
+  let lastIndex = 0
+  let hasReactImports = false
+  const [imports] = parse(_code)
+  imports.forEach(({ s, e, ss, se, n }) => {
+    code += _code.slice(lastIndex, ss)
+    code += _code.substring(ss, s)
+    code += isRelative(n)
+        ? ('@' + n.slice(2))
+        : externals.has(n) ? n : getModuleUrl(n)
+    code += _code.substring(e, se)
+    lastIndex = se
 
-  function updateImportMap(imports) {
-    imports['react'] = getModulePath('react')
-    imports['react-dom'] = getModulePath('react-dom')
 
-    const script = document.createElement('script')
-    script.type = 'importmap-shim'
-    script.innerHTML = JSON.stringify({ imports })
-    document.body.appendChild(script)
-    if (currentImportMap) {
-      currentImportMap.parentNode.removeChild(currentImportMap)
+    if (n === 'react') {
+      const statement = _code.slice(ss, se)
+      if (statement.includes('React')) {
+        hasReactImports = true
+      }
     }
-    currentImportMap = script
+  })
+  code += _code.substring(lastIndex)
+
+  if (!hasReactImports) {
+    code = `import React from 'react';\n${code}`
   }
+  return code
+}
+
+function createRenderer(createModule_, getModuleUrl) {
+  let reactRoot
 
+  async function render(files) {
+    const mod = await createModule_(files, { getModuleUrl })
+    const React_ = await self.importShim('react')
+    const ReactDOM_ = await self.importShim('react-dom')
 
-  function createInlinedModule(code) {
-    return `data:text/javascript;utf-8,${encodeURIComponent(code)}`
+    const _jsx = React_.createElement
+    const root = document.getElementById('root')
+    class ErrorBoundary extends React_.Component {
+      constructor(props) {
+        super(props)
+        this.state = { error: null }
+      }
+      componentDidCatch(error) {
+        this.setState({ error })
+      }
+      render() {
+        if (this.state.error) {
+          return _jsx('div', null, this.state.error.message)
+        }
+        return this.props.children
+      }
+    }
+
+    const isReact18 = !!ReactDOM_.createRoot
+    if (isReact18 && !reactRoot) {
+      reactRoot = ReactDOM_.createRoot(root)
+    }
+    const Component = mod.default
+    const element = _jsx(ErrorBoundary, null, _jsx(Component))
+    if (isReact18) {
+      reactRoot.render(element)
+    } else {
+      ReactDOM_.render(element, root)
+    }
   }
 
-  await setupImportMap()
-  const imports = Object.fromEntries(
-    Object.entries(files).map(([key, code]) => [
-      key,
-      createInlinedModule(code),
-    ])
-  )
+  return render
+}
+
+function createMainScript({ uid }) {
+  const code = (
+`'use strict';
+const _createModule = ${createModule.toString()};
+const _createRenderer = ${createRenderer.toString()};
+
+const getModuleUrl = (m) => window.parent.__devjar__[globalThis.uid].getModuleUrl(m)
 
-  updateImportMap(imports)
-  return self.importShim('index.js')
+globalThis.uid = ${JSON.stringify(uid)};
+globalThis.__render__ = _createRenderer(_createModule, getModuleUrl);
+`)
+  return code
 }
 
-export { createModule }
+function useLiveCode({ getModuleUrl }) {
+  const iframeRef = useRef()
+  const [error, setError] = useState()
+  const rerender = useState({})[1]
+  const scriptRef = useRef(typeof window !== 'undefined' ? document.createElement('script') : null)
+  const uid = useId()
+
+  // Let getModuleUrl executed on parent window side since it might involve
+  // variables that iframe cannot access.
+  useEffect(() => {
+    if (!globalThis.__devjar__) {
+      globalThis.__devjar__ = {};
+    }
+    globalThis.__devjar__[uid] = {
+      getModuleUrl,
+    }
+
+    return () => {
+      if (globalThis.__devjar__) {
+        delete globalThis.__devjar__[uid]
+      }
+    }
+  }, [])
+
+  useEffect(() => {
+    const iframe = iframeRef.current
+    const doc = iframe && iframe.contentDocument
+
+    if (iframe) {
+      const doc = iframe.contentDocument
+      const div = document.createElement('div')
+      const script = scriptRef.current
+      const scriptContent = createMainScript({ uid })
+
+      div.id = 'root'
+      script.type = 'module'
+      script.id = 'main'
+      script.src = `data:text/javascript;utf-8,${encodeURIComponent(scriptContent)}`
+
+      doc.body.appendChild(div)
+      doc.body.appendChild(script)
+    }
+    return () => {
+      if (iframe) {
+        doc.body.removeChild(doc.getElementById('root'))
+        doc.body.removeChild(doc.getElementById('main'))
+      }
+    }
+  }, [])
+
+  const load = useCallback(async (files) => {
+    if (!esModuleLexerInit) {
+      await init
+      esModuleLexerInit = true
+    }
+
+    if (files) {
+      const overrideExternals =
+        new Set(Object.keys(files).filter(name => !isRelative(name) && name !== 'index.js'))
+
+      // Always share react as externals
+      overrideExternals.add('react')
+      overrideExternals.add('react-dom')
+
+      try {
+        const transformedFiles = Object.keys(files).reduce((res, filename) => {
+          const key = isRelative(filename) ? ('@' + filename.slice(2)) : filename
+          res[key] = transformCode(files[filename], getModuleUrl, overrideExternals)
+          return res
+        }, {})
+
+        const iframe = iframeRef.current
+        const script = scriptRef.current
+        if (iframe) {
+          const render = iframe.contentWindow.__render__
+          if (render) {
+            render(transformedFiles)
+          } else {
+            // if render is not loaded yet, wait until it's loaded
+            script.onload = () => {
+              iframe.contentWindow.__render__(transformedFiles)
+            }
+          }
+        }
+        setError()
+      } catch (e) {
+        setError(e)
+      }
+    }
+    rerender({})
+  }, [])
+
+  return { ref: iframeRef, error, load }
+}
+
+export { 
+  createModule,
+  useLiveCode,
+}

package/lib/index.d.ts

@@ -7,7 +7,7 @@ type LiveCodeHandles = {
 }
 
 type Options = {
-  getModulePath(modulePath: string): string
+  getModuleUrl(modulePath: string): string
 }
 
 export function useLiveCode(options: Options): LiveCodeHandles

package/lib/index.mjs

@@ -1,180 +1,2 @@
-import { useEffect, useCallback, useState, useRef } from 'react'
-import { createModule } from './core.mjs'
-import { transform } from 'sucrase'
-import { init, parse } from 'es-module-lexer'
-
-let esModuleLexerInit
-
-const isRelative = s => s.startsWith('./')
-
-function transformCode(_code, getModulePath, externals) {
-  const code = transform(_code, {
-    transforms: ['jsx', 'typescript'],
-  }).code
-
-  return replaceImports(code, getModulePath, externals)
-}
-
-function replaceImports(_code, getModulePath, externals) {
-  let code = ''
-  let lastIndex = 0
-  let hasReactImports = false
-  const [imports] = parse(_code)
-  imports.forEach(({ s, e, ss, se, n }) => {
-    code += _code.slice(lastIndex, ss)
-    code += _code.substring(ss, s)
-    code += isRelative(n)
-        ? ('@' + n.slice(2))
-        : externals.has(n) ? n : getModulePath(n)
-    code += _code.substring(e, se)
-    lastIndex = se
-
-
-    if (n === 'react') {
-      const statement = _code.slice(ss, se)
-      if (statement.includes('React')) {
-        hasReactImports = true
-      }
-    }
-  })
-  code += _code.substring(lastIndex)
-
-  if (!hasReactImports) {
-    code = `import React from 'react';\n${code}`
-  }
-  return code
-}
-
-function createRenderer(createModule_, getModulePath) {
-  let reactRoot
-
-  async function render(files) {
-    const mod = await createModule_(files, { getModulePath })
-    const React_ = await self.importShim('react')
-    const ReactDOM_ = await self.importShim('react-dom')
-
-    const _jsx = React_.createElement
-    const root = document.getElementById('root')
-    class ErrorBoundary extends React_.Component {
-      constructor(props) {
-        super(props)
-        this.state = { error: null }
-      }
-      componentDidCatch(error) {
-        this.setState({ error })
-      }
-      render() {
-        if (this.state.error) {
-          return _jsx('div', null, this.state.error.message)
-        }
-        return this.props.children
-      }
-    }
-
-    const isReact18 = !!ReactDOM_.createRoot
-    if (isReact18 && !reactRoot) {
-      reactRoot = ReactDOM_.createRoot(root)
-    }
-    const Component = mod.default
-    const element = _jsx(ErrorBoundary, null, _jsx(Component))
-    if (isReact18) {
-      reactRoot.render(element)
-    } else {
-      ReactDOM_.render(element, root)
-    }
-  }
-
-  return render
-}
-
-function createMainScript({ getModulePath }) {
-  const code = (
-`'use strict';
-const _createModule = ${createModule.toString()};
-const _createRenderer = ${createRenderer.toString()};
-const _getModulePath = ${getModulePath.toString()};
-
-globalThis.__render__ = _createRenderer(_createModule, _getModulePath);
-`)
-  return code
-}
-
-
-export function useLiveCode({ getModulePath }) {
-  const iframeRef = useRef()
-  const [error, setError] = useState()
-  const rerender = useState({})[1]
-  const scriptRef = useRef(typeof window !== 'undefined' ? document.createElement('script') : null)
-
-  useEffect(() => {
-    const iframe = iframeRef.current
-    const doc = iframe && iframe.contentDocument
-
-    if (iframe) {
-      const doc = iframe.contentDocument
-      const div = document.createElement('div')
-      const script = scriptRef.current
-      const scriptContent = createMainScript({ getModulePath })
-
-      div.id = 'root'
-      script.type = 'module'
-      script.id = 'main'
-      script.src = `data:text/javascript;utf-8,${encodeURIComponent(scriptContent)}`
-
-      doc.body.appendChild(div)
-      doc.body.appendChild(script)
-    }
-    return () => {
-      if (iframe) {
-        doc.body.removeChild(doc.getElementById('root'))
-        doc.body.removeChild(doc.getElementById('main'))
-      }
-    }
-  }, [])
-
-  const load = useCallback(async (files) => {
-    if (!esModuleLexerInit) {
-      await init
-      esModuleLexerInit = true
-    }
-
-    if (files) {
-      const overrideExternals =
-        new Set(Object.keys(files).filter(name => !isRelative(name) && name !== 'index.js'))
-
-      // Always share react as externals
-      overrideExternals.add('react')
-      overrideExternals.add('react-dom')
-
-      try {
-        const transformedFiles = Object.keys(files).reduce((res, filename) => {
-          const key = isRelative(filename) ? ('@' + filename.slice(2)) : filename
-          res[key] = transformCode(files[filename], getModulePath, overrideExternals)
-          return res
-        }, {})
-
-        const iframe = iframeRef.current
-        const script = scriptRef.current
-        if (iframe) {
-          const render = iframe.contentWindow.__render__
-          if (render) {
-            render(transformedFiles)
-          } else {
-            // if render is not loaded yet, wait until it's loaded
-            script.onload = () => {
-              iframe.contentWindow.__render__(transformedFiles)
-            }
-          }
-        }
-        setError()
-      } catch (e) {
-        setError(e)
-      }
-    }
-    rerender({})
-  }, [])
-
-  return { ref: iframeRef, error, load }
-}
-
-export { createModule }
+export { DevJar } from './render.mjs'
+export { useLiveCode } from './core.mjs'

package/lib/module.mjs

@@ -0,0 +1,46 @@
+async function createModule(files, { getModuleUrl }) {
+  let currentImportMap
+  let shim
+
+  async function setupImportMap() {
+    if (shim) return shim
+    window.esmsInitOptions = {
+      shimMode: true,
+      mapOverrides: true,
+    }
+    shim = import(/* webpackIgnore: true */ getModuleUrl('es-module-shims'))
+    await shim
+  }
+
+  function updateImportMap(imports) {
+    imports['react'] = getModuleUrl('react')
+    imports['react-dom'] = getModuleUrl('react-dom')
+
+    const script = document.createElement('script')
+    script.type = 'importmap-shim'
+    script.innerHTML = JSON.stringify({ imports })
+    document.body.appendChild(script)
+    if (currentImportMap) {
+      currentImportMap.parentNode.removeChild(currentImportMap)
+    }
+    currentImportMap = script
+  }
+
+
+  function createInlinedModule(code) {
+    return `data:text/javascript;utf-8,${encodeURIComponent(code)}`
+  }
+
+  await setupImportMap()
+  const imports = Object.fromEntries(
+    Object.entries(files).map(([key, code]) => [
+      key,
+      createInlinedModule(code),
+    ])
+  )
+
+  updateImportMap(imports)
+  return self.importShim('index.js')
+}
+
+export { createModule }

package/lib/render.mjs

@@ -0,0 +1,21 @@
+import React, { useEffect, useRef } from 'react'
+import { useLiveCode } from './core.mjs'
+
+const defaultOnError = typeof window !== 'undefined' ? console.error : (() => {})
+
+export function DevJar({ files, getModuleUrl, onError = defaultOnError, ...props }) {
+  const onErrorRef = useRef(onError)
+  const { ref, error, load } = useLiveCode({ getModuleUrl })
+
+  useEffect(() => {
+    onErrorRef.current(error)
+  }, [error])
+
+  // load code files and execute them as live code
+  useEffect(() => {
+    load(files)
+  }, [files])
+
+  // Attach the ref to an iframe element for runtime of code execution
+  return React.createElement('iframe', { ...props, ref })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devjar",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./lib/index.mjs",
@@ -17,20 +17,20 @@
     "dev": "next dev ./docs"
   },
   "peerDependencies": {
-    "react": "^17.0.0 || ^18.0.0"
+    "react": "^18.2.0"
   },
   "dependencies": {
-    "es-module-lexer": "^0.10.5",
-    "es-module-shims": "^1.5.4",
-    "sucrase": "3.21.0"
+    "es-module-lexer": "0.10.5",
+    "es-module-shims": "1.5.9",
+    "sucrase": "3.23.0"
   },
   "devDependencies": {
     "codice": "latest",
     "devjar": "link:./",
     "lodash-es": "^4.17.21",
-    "next": "canary",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
-    "sugar-high": "^0.4.4"
+    "next": "^13.1.6",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "sugar-high": "^0.4.5"
   }
 }