|
1 | | -# javascript-library-template [](https://github.com/vvo/javascript-library-template/blob/master/LICENSE) [](https://github.com/vvo/javascript-library-template/actions) [](https://codecov.io/gh/vvo/javascript-library-template)  [](https://bundlephobia.com/result?p=javascript-library-template) |
2 | | - |
3 | | -<p align="center"> |
4 | | -<small><b>Click below to create a new GitHub repository using this template:</b></small> |
5 | | -<br/><br/><a href="https://github.com/vvo/javascript-library-template/generate"> |
6 | | -<img src="https://img.shields.io/badge/use%20this-template-blue?logo=github"> |
7 | | -</a> |
8 | | -</p> |
| 1 | +# aws-lambda-nodejs-rollup [](https://github.com/vvo/aws-lambda-nodejs-rollup/blob/master/LICENSE) [](https://github.com/vvo/aws-lambda-nodejs-rollup/actions) [](https://codecov.io/gh/vvo/aws-lambda-nodejs-rollup)  [](https://bundlephobia.com/result?p=aws-lambda-nodejs-rollup) |
9 | 2 |
|
10 | 3 | --- |
11 | 4 |
|
12 | | -**This JavaScript library template** allows you to easily develop, collaborate on and publish a JavaScript library with all the modern tooling you'd expect from the current JavaScript ecosystem. |
13 | | - |
14 | | -**Why should you use this?** One of the hidden challenges of authoring opensource JavaScript libraries is to provide a project that is easy to contribute to. You want people to join your project. Doing so requires a good amount of boilerplate: testing, code coverage, dependencies maintenance, release scripts, tooling requirements (Node.js, Yarn and which versions are we using again?), code editor configuration, formatting, linting... Well, this is the goal of this template: **to provide sensible and modern defaults to all those subjects**. So that once set up, you can focus on ⌨️ coding, 🙌 collaborating and 🚀 shipping. |
| 5 | +_[CDK](https://aws.amazon.com/cdk/) Construct to build Node.js AWS lambdas using [rollup.js](https://rollupjs.org/)_ |
15 | 6 |
|
16 | | -**The goals of the template are to:** |
| 7 | +_Table of contents:_ |
17 | 8 |
|
18 | | -- Ease the contribution of the library by providing reproducible environments for developers and CI |
19 | | -- Automate as much as possible, from testing to releasing and upgrading dependencies |
20 | | -- Provide good defaults for users of [Visual Studio Code](https://code.visualstudio.com/) |
| 9 | +- [Usage example](#usage-example) |
| 10 | +- [Features](#features) |
| 11 | +- [Why?](#why) |
| 12 | +- [Roadmap](#roadmap) |
| 13 | +- [How to make changes and test locally](#how-to-make-changes-and-test-locally) |
| 14 | +- [Thanks](#thanks) |
21 | 15 |
|
22 | | -**Features:** |
| 16 | +## Usage example |
23 | 17 |
|
24 | | -- [EditorConfig](https://editorconfig.org/): easy contributions from any code editor. |
25 | | -- [ESLint](https://eslint.org/): launched in the `test` script. |
26 | | -- [Prettier](https://prettier.io/): launched in the `test` script, with markdown, JavaScript, CSS and JSON files support (including automatic [`package.json` formatting](https://github.com/matzkoh/prettier-plugin-packagejson)). |
27 | | -- Automatic VSCode formatting and linting: using VSCode extensions recommendations and workspace settings in .`vscode/` folder. |
28 | | -- [Yarn](http://yarnpkg.com/) version pinning: via [Yarn policies](https://classic.yarnpkg.com/en/docs/cli/policies/), so anyone contributing or any system accessing your library will use the same Yarn version without having to think about it. |
29 | | -- [Node.js](https://nodejs.org/) version pinning: via [nvm](https://github.com/nvm-sh/nvm), so anyone contributing or any system accessing your library will use the same Node.js version without having to think about it. |
30 | | -- [Jest](https://jestjs.io/): launched in the `test` script, also with the right VSCode settings providing a testing workflow inside VSCode using [`vscode-jest`](https://github.com/jest-community/vscode-jest) extension. |
31 | | -- [GitHub actions](https://github.com/features/actions): automatic testing and releasing from GitHub: npm publish and GitHub releases are automatically created. Note that the package.json in your repository is never updated (the version is always `0.0.0-development`), only the one in npm is updated. This is surprising at first but as long as you display the published version in your README (like this template does) then you're fine. Find more information about this in the [semantic-release documentation](https://semantic-release.gitbook.io/semantic-release/support/faq#why-is-the-package-jsons-version-not-updated-in-my-repository). |
32 | | -- [semantic-release](https://semantic-release.gitbook.io/semantic-release/): allows for automatic releases based on semver.org and [conventional commits specification](https://www.conventionalcommits.org/). The defaults are taken from the [Angular git commit guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines). |
33 | | -- [Codecov](https://codecov.io/): launched in the `test` script on CI, ensures code coverage does not decrease on pull requests _(free for public and private repositories)_. |
34 | | -- [Renovate](https://renovate.whitesourcesoftware.com/) configurated with the [JavaScript library preset](https://docs.renovatebot.com/presets-config/#configjs-lib): this will automatically update your dependencies by opening pull request for you to approve or not. So you never have to think about it _(free for public and private repositories)_. |
| 18 | +```bash |
| 19 | +yarn add aws-lambda-nodejs-rollup |
| 20 | +``` |
35 | 21 |
|
36 | | -## Setup |
| 22 | +```js |
| 23 | +// infra/super-app-stack.js |
| 24 | +const sns = require("@aws-cdk/aws-sns"); |
| 25 | +const subscriptions = require("@aws-cdk/aws-sns-subscriptions"); |
| 26 | +const core = require("@aws-cdk/core"); |
| 27 | +const { NodejsFunction } = require("aws-lambda-nodejs-rollup"); |
| 28 | + |
| 29 | +module.exports = class SuperAppProductionStack extends core.Stack { |
| 30 | + constructor(scope, id, props) { |
| 31 | + super(scope, id, props); |
| 32 | + |
| 33 | + const slackNotificationsLambda = new NodejsFunction( |
| 34 | + this, |
| 35 | + "slack-notifications-lambda", |
| 36 | + { |
| 37 | + entry: "events/slack-notifications.js", // required |
| 38 | + }, |
| 39 | + ); |
| 40 | + } |
| 41 | +}; |
| 42 | +``` |
37 | 43 |
|
38 | | -Using this template requires a bit of setup, but way less than if you had to start from 0. Here's what you need to do: |
| 44 | +```js |
| 45 | +// events/slack-notifications.js |
| 46 | +import { WebClient as SlackWebClient } from "@slack/web-api"; |
39 | 47 |
|
40 | | -**Required steps:** (needed every time you want to use the template) |
| 48 | +export function handler(event) { |
| 49 | + const message = event.Records[0].Sns.Message; |
| 50 | + // do something with message |
| 51 | +} |
| 52 | +``` |
41 | 53 |
|
42 | | -1. [Create a new repository](https://github.com/new) on GitHub based on this template |
43 | | -1. [Setup renovate](https://github.com/apps/renovate) for your new repository. If you previously installed the Renovate application to your account then this is just a box to tick when creating the repository |
44 | | -1. [Clone the new repository](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) |
45 | | -1. Change the package name and description in `package.json` |
46 | | -1. [Setup Codecov](https://github.com/apps/codecov) for your new repository. If you previously installed the Codecov application to your account then this is just a box to tick when creating the repository |
47 | | -1. Setup semantic releases: run `yarn semantic-release-cli setup` in a terminal (This will ask for your npm and GitHub credentials) |
48 | | -1. Add the previously generated `GH_TOKEN` and `NPM_TOKEN` secrets to the [GitHub secrets](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets) of the new repository |
49 | | -1. Install dependencies: run `yarn` in your terminal |
50 | | -1. **Develop your library**: change code in `lib/` |
51 | | -1. **Test your library**: you can either see tests results inside VSCode directly or run `yarn jest --watch` |
52 | | -1. **Check formatting of your code**: run `yarn check-formatting` in your terminal |
53 | | -1. **Create your first release**: [open a pull request](https://help.github.com/en/desktop/contributing-to-projects/creating-a-pull-request) on your project, wait for tests to pass, merge and 💥 your library will be automatically released to npm and a GitHub release will be created |
| 54 | +## Features |
54 | 55 |
|
55 | | -**Optional steps:** (needed only if you're doing them for the first time) |
| 56 | +- fast, [no-docker](https://github.com/aws/aws-cdk/issues/9120) CDK construct |
| 57 | +- lambda output respects original files structure and node_modules (no inlining) |
| 58 | +- lambda output only contains the necessary files, no README, tests, ... |
| 59 | +- bundling happens in temporary directories, it never writes in your project directory |
| 60 | +- source map support |
56 | 61 |
|
57 | | -1. If you're not using VSCode, if your editor has no EditorConfig support, then [setup EditorConfig](https://editorconfig.org/#download) [EditorConfig support](https://editorconfig.org/) |
58 | | -1. Make sure you have [npm 2fa auth-only](https://docs.npmjs.com/about-two-factor-authentication#authorization-only) configured. Releases can't be automated if you have 2fa setup for both authentication and publish. See https://semantic-release.gitbook.io/semantic-release/usage/ci-configuration#authentication-for-plugins |
59 | | -1. [Install nvm](https://github.com/nvm-sh/nvm) |
60 | | -1. [Install yarn](https://classic.yarnpkg.com/en/docs/install#alternatives-stable) |
| 62 | +## Why? |
61 | 63 |
|
62 | | -## Status and next steps |
| 64 | +There's already a dedicated [aws-lambda-nodejs module for CDK](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-lambda-nodejs-readme.html) but I had two major issues with it: |
63 | 65 |
|
64 | | -The template is still pretty new (March 2020) and was done to author JavaScript libraries using ECMAScript modules for Node.js >= 12. Gradually, or given requests, **we could update it to support**: |
| 66 | +1. **CDK uses docker** for anything lambda build related. This means it mounts your whole Node.js project (not just the lambda code) inside Docker before running a bundler like Parcel. This is perfectly fine and performant on Linux and Windows, but this is **extremely slow on macOS**: a single cdk synth would take 2 minutes for a 3 lines lambda. Since it might take a very long time for Docker on macOS to get as fast as on Linux. Even their latest update ([mutagen](https://docs.docker.com/docker-for-mac/mutagen/)), while significantly faster, still takes 20s just to mount a Node.js project. |
| 67 | +2. aws-lambda-nodejs generates single files bundles with every local and external module inlined. Which makes it very hard to debug and read on the AWS console. I wanted a lambda output that mimicks my project file organization. |
65 | 68 |
|
66 | | -- Using different CI environments than GitHub actions |
67 | | -- Authoring browser libraries |
68 | | -- Generating `README.md` table of contents automatically |
69 | | -- Better default `README.md` content (Install, API, Examples, ...) |
70 | | -- `create-javascript-library` command line that would get most of the setup done easily |
71 | | -- `.github` Pull requests template, issues templates, CONTRIBUTING files |
72 | | -- add or change scripts to allow for auto-formatting |
73 | | -- provide documentation on how to protect branches on GitHub |
74 | | -- provide scripts to easily open a pull request once a branch is created |
75 | | -- provide a way to check for semantic commits in PR |
76 | | -- contributors list |
77 | | -- https://github.com/apps/semantic-pull-requests |
| 69 | +I want to be clear: I respect a LOT the work of the CDK team, and especially [@jogold](https://github.com/jogold/), author of aws-lambda-nodejs) that helped me a lot into debugging performance issues and explaining to me how everything works. |
78 | 70 |
|
79 | | -If you'd like to participate, if you have bugs or new ideas, [open an issue](https://github.com/vvo/javascript-library-template/issues/new) or a pull request. |
| 71 | +## Roadmap |
80 | 72 |
|
81 | | -## Recipes |
| 73 | +This is a list of features I thought could be interesting to users. If you need on of them, please contribute to the project. |
82 | 74 |
|
83 | | -### Using `yarn link` |
| 75 | +- [ ] Allow passing rollup options, like externals |
| 76 | +- [ ] Allow usage without the need of `entry`: `new NodejsFunction(this, "slack-notifications-lambda");` that would mimic https://docs.aws.amazon.com/cdk/api/latest/docs/aws-lambda-nodejs-readme.html#nodejs-function |
| 77 | +- [ ] Generate a bundle where entry is moved to /index.js |
| 78 | +- [ ] Use [jsii](https://github.com/aws/jsii) to build for other languages |
| 79 | +- [ ] Ask CDK team if this could live under their repositories |
| 80 | +- [ ] Allow native modules, with option `nativeModules`. They would have to be installed into a temp folder with `npm_config_arch` and `npm_config_platform` and aliased in rollup configuration |
| 81 | +- [ ] Add tests |
84 | 82 |
|
85 | | -To use `yarn link` efficiently, do this: |
| 83 | +## How to make changes and test locally |
86 | 84 |
|
87 | | -```bash |
88 | | -> cd my-library |
89 | | -> yarn link |
90 | | -> yarn build --watch |
91 | | -> cd ../my-other-library |
92 | | -> yarn link my-library |
| 85 | +``` |
| 86 | +// fork and clone |
| 87 | +cd aws-lambda-nodejs-rollup |
| 88 | +yarn |
| 89 | +yarn link |
| 90 | +yarn start |
| 91 | +
|
| 92 | +# in another terminal and project where you want to test changes |
| 93 | +yarn link aws-lambda-nodejs-rollup |
| 94 | +# cdk commands will now use your local aws-lambda-nodejs-rollup |
93 | 95 | ``` |
94 | 96 |
|
95 | | -### Reformating all code |
| 97 | +## Thanks |
96 | 98 |
|
97 | | -```bash |
98 | | -yarn format |
99 | | -``` |
| 99 | +- the CDK team for this awesome project |
| 100 | +- [@jogold](https://github.com/jogold/) for his time while helping me debugging performance issues on Docker |
0 commit comments