Add parser for pyodide.js and pyodide.mjs to avoid webpack traversing dependencies

.eslintrc

@@ -6,15 +6,28 @@
   },
   "env": {
     "node": true,
-    "es6": true
+    "es6": true,
+    "browser": true
   },
   "plugins": ["@typescript-eslint"],
   "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended", "prettier"],
   "rules": {
-    "@typescript-eslint/no-var-requires": 0
+    "no-constant-condition": 0,
+    "@typescript-eslint/no-var-requires": 0,
+    "@typescript-eslint/no-unused-vars": [
+      "warn", // or "error"
+      {
+        "argsIgnorePattern": "^_{1,}$",
+        "varsIgnorePattern": "^_{1,}$",
+        "caughtErrorsIgnorePattern": "^_{1,}$"
+      }
+    ],
+    "@typescript-eslint/ban-ts-comment": 0
   },
   "globals": {
     "describe": "readonly",
+    "beforeEach": "readonly",
+    "afterEach": "readonly",
     "it": "readonly"
   }
 }

.github/workflows/build-and-test.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x, 16.x]
+        node-version: [18.x, 20.x]
 
     steps:
       - uses: actions/checkout@v3
@@ -21,5 +21,4 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
       - run: npm ci
-      - run: npm run build --if-present
       - run: npm test

.vscode/launch.json

@@ -19,6 +19,24 @@
       "runtimeExecutable": "npm",
       "skipFiles": ["<node_internals>/**"],
       "type": "node"
+    },
+    {
+      "name": "Example: common:build",
+      "request": "launch",
+      "runtimeArgs": ["run-script", "build"],
+      "runtimeExecutable": "npm",
+      "cwd": "${workspaceFolder}/examples/commonjs",
+      "skipFiles": ["<node_internals>/**"],
+      "type": "node"
+    },
+    {
+      "name": "Example: esm:build",
+      "request": "launch",
+      "runtimeArgs": ["run-script", "build"],
+      "runtimeExecutable": "npm",
+      "cwd": "${workspaceFolder}/examples/esm",
+      "skipFiles": ["<node_internals>/**"],
+      "type": "node"
     }
   ]
 }

CONTRIBUTING.md

@@ -7,15 +7,36 @@ Thank you for your interest in contributing to Pyodide Webpack Plugin! There are
 To contribute code, see the following steps,
 
 1. Fork the Pyodide repository https://github.com/pyodide/pyodide-webpack-plugin on Github.
-2. Clone your fork of Pyodide\
+2. Clone your fork of Pyodide Webpack Plugin\
    `git clone https://github.com/<your-username>/pyodide-webpack-plugin.git`\
    and add the upstream remote,\
    `git remote add upstream https://github.com/pyodide/pyodide-webpack-plugin.git`
-3. Nodejs [16.x+](https://nodejs.org/en/)
+3. Nodejs [18.x+](https://nodejs.org/en/)
 4. Install requirements\
    `npm i`
 5. See Testing and benchmarking documentation.
 
+## Testing
+
+Run the full suite of tests including a fresh build, lint, formatting, and unit tests with:
+
+```
+npm test
+```
+
+You can run individual steps of the test by looking in [package.json](./package.json) for different scripts. `npm run unit` is useful for rerunning unit tests quickly.
+
+### Unit Tests
+
+Unit testing currently tests against the [examples](./examples/). There are a few things to note:
+
+- Tests happen against the built plugin. You must run `npm run build` before you test if any of your code has changes. `npm test` runs the build as part of the test phase.
+- Your example must contain a `webpack.config.js` and must export webpack itself
+- New examples need to be initialized with npm workspaces `npm init -w examples/<example name>`
+- New examples are automatically picked up for the build targets and test phase
+
+> running `npx webpack --watch` can be faster than running `npm run build` if you are iterating over the plugin and testing. Use in conjunction with `npm run unit` for fast test iteration.
+
 ## Code of Conduct
 
 Pyodide has adopted a [Code of Conduct](https://pyodide.org/en/stable/project/code-of-conduct.html#code-of-conduct) that we expect all contributors and core members to adhere to.

README.md

@@ -29,7 +29,7 @@ pnpm add -D pyodide @pyodide/webpack-plugin
 Add the plugin to your webpack config
 
 ```js
-const PyodidePlugin = require("@pyodide/webpack-plugin");
+const { PyodidePlugin } = require("@pyodide/webpack-plugin");
 
 module.exports = {
   plugins: [new PyodidePlugin()],
@@ -52,6 +52,8 @@ async function main() {
 main();
 ```
 
+See [examples](./examples/).
+
 ## Options
 
 - [globalLoadPyodide](#globalLoadPyodide)
@@ -79,45 +81,6 @@ Default: `https://cdn.jsdelivr.net/pyodide/v${installedPyodideVersion}/full/`\
 Required: false\
 _Description_: CDN endpoint for python packages. This option differs from [loadPyodide indexUrl](https://pyodide.org/en/stable/usage/api/js-api.html) in that it only impacts pip packages and _does not_ affect the location the main pyodide runtime location. Set this value to "" if you want to keep the pyodide default of accepting the indexUrl.
 
-## Known issues with esm
-
-Depending on your webpack configuration you may run into issues with webpack trying to parse your pyodide.mjs file.
-
-**Can't resolve 'url' in ...**
-
-[Issue #8](https://github.com/pyodide/pyodide-webpack-plugin/issues/8) deals with this error and pyodide esm. To fix this issue:
-
-- `npm i -D url`
-- Add a [fall back](https://webpack.js.org/configuration/resolve/#resolvefallback) to your webpack config
-  ```js
-  resolve: {
-    fallback: {
-      url: require.resolve("url/"),
-    },
-  },
-  ```
-
-**Cannot find module '<...>/pyodide.asm.js.**
-
-This can happen when webpack munges esm import statements to \_\_webpack_require\_\_ when you actually intend import to work in the browser.
-
-- `npm i -D string-replace-loader`
-- Add a [rule](https://webpack.js.org/configuration/module/#rule) to your webpack config
-  ```js
-  {
-    test: /pyodide\.m?js$/,
-    use: [
-      {
-        loader: 'string-replace-loader',
-        options: {
-          search: 'import(',
-          replace: 'import(/* webpackIgnore: true */ '
-        }
-      }
-    ]
-  }
-  ```
-
 ## Contributing
 
 Please view the [contributing guide](./CONTRIBUTING.md) for tips on filing issues, making changes, and submitting pull requests. Pyodide is an independent and community-driven open-source project. The decision-making process is outlined in the [Project governance](https://pyodide.org/en/stable/project/governance.html).

examples/README.md

@@ -0,0 +1,10 @@
+# Examples
+
+Example usage of pyodide webpack plugin. Download / copy the example folder you wish to try out and run the following commands:
+
+```
+npm i
+npm run serve
+```
+
+This will install the necessary dependencies and start webpack dev server. Open your browser to the URL output in the terminal and view the develop console to see the output of pyodide.

examples/commonjs/.gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

examples/commonjs/index.js

@@ -0,0 +1,15 @@
+const { loadPyodide } = require("pyodide");
+
+async function main() {
+  let pyodide = await loadPyodide({
+    indexURL: `${window.location.origin}/pyodide`,
+  });
+  // Pyodide is now ready to use...
+  console.log(
+    pyodide.runPython(`
+    import sys
+    sys.version
+  `)
+  );
+}
+main();