NatML

Zero deployment machine learning.

Usage

In Node, simply npm i natml.

On the browser, you can do:

<script src="https://unpkg.com/natml@latest/dist/natml.browser.js"></script>

Then, you can reference the library using window.natml.

Build Notes

This is an isomorphic package. To support functionality that needs a different implementation in the browser and Node, there are two files -- src/utils/NatMLEnvironment.ts and src/utils/NatMLEnvironment.browser.ts -- which provide the Node and browser implementations, respectively, of all functionality that differs across platforms.

Code that wants to use this functionality must always import from the src/utils/NatMLEnvironment.ts file. Then, when building for browsers, these imports will be rewritten to reference src/utils/NatMLEnvironment.browser.ts.

It would be less confusing if we had a src/utils/NatMLEnvironment.node.ts file, rather than putting the Node implementation in src/utils/NatMLEnvironment.ts. That would allow us to use src/utils/NatMLEnvironment.ts as be a dummy/stub file, with a comment explaining that references to it will be replaced with the target platform's environment. However, our build setup doesn't support this.

The build works like this:

Webpack builds a single UMD file for the browser, which we publish using unpkg and which we reference in the browser field of package.json. By referencing this bundle in browser, bundlers will use it when they're building for the browser (like a React app bundled by Webpack that imports our pacakge). Note that this single UMD file won't be tree-shakable, so we may also want to use webpack down the line to generate an ESM or CJS entry point, that still has the browser dependencies. When building with Webpack, we use a plugin to replace all imports of src/utils/NatMLEnvironment.ts with src/utils/NatMLEnvironment.browser.ts.

Meanwhile, when building for Node, we don't need a single output file. However, we do want our package to come with type definitions whenever it's used with npm (whether it'll ultimately be bundled into a browser app or used on the server). That means, we need to do one build using the TS compiler, as webpack doesn't seem to easily/cleanly support generating the type declaration files. We'll use this build from the TS compiler to power imports of our package for server-side use (through main and exports in package.json), while exposing the declarations to all npm users through typings in package.json.

However, when we're building with the TS compiler, it can't rewrite import paths as part of its emit, which is why the file we import to get the platform-specific functionality (i.e., src/utils/NatMLEnvironment.ts) has to actually exist on the filesystem and contain the Node implementation.

N.B.: a totally different option here would've been to put only the isomorphic code in its own package (e.g., @natsuite/platform-helpers), which would have a different entrypoint for the browser and node. That would've allowed tree-shaking when the SDK is included in a bundler-built frontend app, but would've added the complexity of needing to maintain a separate package. Long-term, a separate isomorphic package is probably a better approach, but it's not needed for now.