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.