Before we get started - if you're just here because you want a plug 'n' play starter, here's a project generator and here's an example repository! 🚀
Getting Typescript to run is usually pretty simple. You just follow a few lines of instructions from the first google link. Getting the project from that point to something that you can deploy with confidence is often surprisingly hard though. To get there, you'll at the very least want to have testing and linting set up. Tree shaking is another thing you'll probably want to be able to drastically reduce your bundle sizes.
This is going to be a walkthrough of my opinionated approach to achieving a simple but extensible setup that accomplishes these simple goals for a Serverless AWS project.
Project Initialization
Let's start off by creating a new project. Make sure you're in an empty directory and run npm init -y. We're going to need a few tools to set this up:
Let's add those as devDependencies right of the bat as well
yarn add eslint jest @types/jest serverless serverless-webpack ts-jest ts-loader typescript webpack -D
Application Code & Tests
We'll need some example Typescript code to run in our app. I prefer placing the application code in an src folder and the test code in a tests folder to keep them separate.
export const handler = async (event: any, context: any) => {
return 'Hello from handler!';
};
import { handler } from '../src/myFunction';
describe('[myFunction]', () => {
it('should not crash', async () => {
await handler({}, {});
});
});
In order to transpile and run the Typescript code, we'll need a tsconfig.json. We can generate one to start from by running yarn tsc --init. Let's change both the target and lib to "ES2020" as we want to be able to use modern ECMAScript features.
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"lib": ["ES2020"],
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
}
}
All we need now to be able to start developing and testing our app is to add a Jest configuration file. The default settings for Jest are pretty sensible to we don't have to care about most of those right now except for setting preset to "ts-jest" and the testEnvironment to "node".
module.exports = {
preset: 'ts-jest',
testEnvironment: 'node',
};
We can now finally run our tests with yarn jest to confirm that everything seems to work so far.
Excellent, our tests are passing! 🎉
Linting
We'll be using ESLint for static code analysis and code style enforcement. ESLint configurations can quickly become a mess and it's by nature very subjective so let's keep it simple here. When we run yarn eslint --init we'll get to answer a few questions about our preferences. In the image below I chose to create a small custom set of rules rather than using one of the "popular style guides" but it's completely up to you.
This is how mine ended up looking:
module.exports = {
env: {
es2021: true,
node: true,
},
extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
parser: '@typescript-eslint/parser',
parserOptions: {
ecmaVersion: 12,
sourceType: 'module',
},
plugins: ['@typescript-eslint'],
rules: {
indent: ['error', 2],
'linebreak-style': ['error', 'unix'],
quotes: ['error', 'single'],
semi: ['error', 'always'],
},
ignore: ['webpack.config.js'],
};
The AirBnb style guide has a few conflicts with our Typescript setup out of the box so if you choose to extend AirBnb style guide you'll have to do these steps as well:
- add
"jest" to the env configuration
- add
'plugin:import/typescript' to extends & import to plugins to get rid of module resolution errors
- disable explicit file extension rule by adding
'import/extensions': 'off' to rules
Packaging & Deploying
Lastly, we need to configure Webpack and Serverless in order to build and deploy our app. For the Webpack configuration, we can use a pretty simple setup where we specify ts-loader to be used as the loader for Typescript files.
const path = require('path');
const slsw = require('serverless-webpack');
module.exports = {
mode: slsw.lib.webpack.isLocal ? 'development' : 'production',
entry: slsw.lib.entries,
resolve: {
extensions: ['.ts', 'tsx']
},
target: 'node',
module: {
rules: [
{
test: /\.(tsx?)$/,
loader: 'ts-loader',
exclude: [
[
path.resolve(__dirname, 'node_modules'),
path.resolve(__dirname, '.serverless'),
path.resolve(__dirname, '.webpack'),
],
],
},
],
},
};
and finally, for the Serverless configuration we'll, in addition to some basic information about our app, add the following:
serverless-webpack to the list of plugins- Set
package.individually to true in order to bundle each function separately so that we can reduce the bundle size for each function by only including exactly what's needed to run it
- As we've been using Yarn we should set the Webpack packager to
yarn so that it'll respect our lock file.
// serverless.yml
service: sls-ts
plugins:
- serverless-webpack
package:
individually: true
custom:
webpack:
packager: yarn
provider:
name: aws
region: eu-north-1
runtime: nodejs14.x
functions:
myFunction:
handler: src/myFunction.handler
That's it! Hit yarn serverless deploy to deploy the project! We can verify that it works by running yarn serverless invoke -f myFunction
Wrapping up
Project configuration is highly subjective and the complexity often grows as the projects grows but I hope this can serve as a starting point to build upon!
If you enjoyed this guide and want to see more, follow me on Twitter at @TastefulElk where I frequently write about serverless tech, AWS and developer productivity!
Happy hacking! 🚀
Resources
