Browser builds


On this page

    Using bundlers such as Webpack and browserify, you can bundle your custom Comunica engine for the browser.

    For this, you have to go the following.

    If you just want to make use of default Comunica engines such as Comunica SPARQL, refer to the guide on querying in a JavaScript browser app.
    A full example of a custom Comunica engine that is browser-ready can be found here.

    1. Compile the config to JavaScript

    Not all parts of Comunica can be executed in the browser. Namely, the dynamic version of Comunica that can read from a config on the local file system.

    As such, if we want to expose our engine in the browser, we have to compile our config to a JavaScript file. This can be done using the comunica-compile-config from @comunica/runner.

    For this, add @comunica/runner as a dev dependency to your package.json, and add the following script (assuming your config exists at config/config-default.json):

    {
      ...
      "scripts": {
          ...
          "prepublishOnly": "npm run build:engine",
          "build:engine": "comunica-compile-config config/config-default.json > engine-default.js"
      }
    }
    

    2. Create a browser-specific entrypoint

    Next, create a file called lib/index-browser.ts, which will become the browser variant of lib/index.ts. lib/index-browser.ts should at least contain the following:

    export * from './QueryEngine';
    

    3. Expose the browser-specific entrypoint

    After that, we have to tell the browser bundling tools that they need to look at index-browser.js instead of index.js for browser apps. For this, add the following to your package.json:

    {
      ...
      "browser": {
        "./lib/index.js": "./lib/index-browser.js"
      }
    }
    

    4. Building for the browser

    Now you're ready to compile your application for the browser using tools such as Webpack.

    As of Webpack 5, the Node.js polyfills are not shipped anymore by default. Since Comunica requires those, they will have to be added manually, which can be done using the node-polyfill-webpack-plugin.

    Please refer to the documentation of Webpack on how to configure this build process.

    Below you can find an example configuration file for Webpack, which may require some fine-tuning depending on your use case:

    const path = require('path');
    const ProgressPlugin = require('webpack').ProgressPlugin;
    const NodePolyfillPlugin = require("node-polyfill-webpack-plugin");
    
    module.exports = {
      entry: [ '@babel/polyfill', path.resolve(__dirname, 'my-app.js') ],
      output: {
        filename: 'my-app-browser.js',
        path: __dirname, 
        libraryTarget: 'window',
      },
      devtool: 'source-map',
      module: {
        rules: [
          {
            test: /\.js$/,
            loader: 'babel-loader',
            exclude: /node_modules/,
          },
        ]
      },
      plugins: [
        new NodePolyfillPlugin(),
        new ProgressPlugin(),
      ]
    };