Add Node guide

[jaredpalmer]

No description provided.

[James-Quigley]

What kind of things would you want in the Node guide?

[jaredpalmer]

So this could be used to build a CLI tool (it will preserve shebangs) or even a lambda function. Probably want to just show off adding @types/node maybe?

[aleclarson]

And you'll want "moduleResolution": "node" in your tsconfig.json

[kevinold]

@jaredpalmer I'd love to use tsdx to compile code for Lambda's, but think I'm missing something in that a yarn build doesn't include dependencies in the dist files.

I have a simple tsdx project here with 2 dependencies, but neither (aws-sdk and lodash/kebabCase) and neither are in the dist from a yarn build.

What am I missing to allow these dependencies to be in the build files so I could use this in a Lambda?

[kevinold]

Found the answer in that UMD was disabled by default -- e81f5a6

[kevinold]

Thought I found the answer, but even producing a UMD build does not bundle the dependencies. I took a look at the rollup config and feel like it should work, but not certain what I'm missing.

Any help is appreciated.

[cogell]

@kevinold did you ever figure this out? just came to tsdx looking for a starter project to use for writing some lambdas

[kevinold]

@cogell I did not find a solution

[lpolito]

So I just dug into this because I also wanted to start using this for building lambda functions. I was able to initially make simple code, but as soon as you add dependencies it gets complicated.

There's a few limitations with the current implementation that make this difficult - namely around the rollup configuration.

Currently createRollupConfig.ts does the following:

1. Marks all imports as external if they are not relative / are absolute (seen here).
   • The intention is so that rollup doesn't bundle external dependencies. It assumes they're available in the environment.
2. Only uses the commonjs rollup plugin if the umd format is used (seen here).
   • The commonjs plugin is needed because there's a chance your dependencies are not written in es6 and need to be converted so you can bundle them.

Both of these become an issue for this use case. Firstly we need all external dependencies bundled. Secondly a number of our bundles are probably not written in es6 and we'll need this conversion.

My work around is fairly simple, but there's potential implications I don't currently full understand:

Create a tsdx.config.js (in your project root):

const commonjs = require('@rollup/plugin-commonjs');

module.exports = {
  rollup(config) {
    // Delete the external config property.
    // This essentially means we're allowing all packages to be bundled.
    delete config.external;

    // Manually use the commonjs plugin.
    // This is opposed to specifying umd as the format as there's more implications that, again, are unclear.
    config.plugins.push(commonjs());

    return config;
  },
};

You can then call yarn build and use the resulting dist/ as your lambda. When building expect a ton of warnings around dependencies, e.g.

'zlib' is imported by node_modules/node-fetch/lib/index.mjs, but could not be resolved – treating it as an external dependency

I want to either update the docs with this in mind, or completely rethink how this is handled using the guided installation. The latter would be a lot of work, but I think the benefits would be great.

I hope I covered everything I found, as I've been fighting this for a few hours.

[agilgur5]

@lpolito I looked into the warnings, and I'm pretty sure the ones you're getting are for Node built-ins (zlib is a built-in, and that's the only one you listed). Which means they should be ignorable. If you'd like to silence them, you can configure external to do so. Basically just uses the builtin-modules package as a safelist.

RE: UMD vs. CJS, I think you should be fine using UMD as it works for Node too (it is "universal"). I'm not 100% sure how it imports built-ins, but IIRC UMD will use the require function if it exists.