Quick Invoke Extension

This extension helps you invoke your AWS Lambda code on your local machine using either:

• direct evaluation with Node.js (in Quick Invoke mode)
• using the sam cli & Docker container (in SAM CLI mode)

How it works

You will create a .quick_invoke file for each lambda you want to test and one or multiple .json event files.

Quick Invoke extension will search for all .quick_invoke files in your workspace and for all .json event files in the containing folder of the quick_invoke file and all it's subfolders.

The extension will show a tree view in the side container view with all the event files it has found.

You will be able to invoke the event from the list or re-invoke the last one used from the bottom status bar.

When invoked, the extension will open a terminal and execute the propper command to run your code and then log the result.

Installing dependencies

• install aws cli tool
  • note: not tested with aws cli version 2 yet
• configure your aws profile
  • note: quick invoke also supports multiple profiles configurations

Additional steps required for Quick Invoke mode:

• install the same version of node as your lambda code (recommendation: use nvm for this)
• install env-cmd as a dev dependency (optional but recommended)
• install aws-sdk (required if your lambda makes calls to aws-sdk like DynamoDB and other aws frameworks)
  • aws-sdk comes pre-installed in the lambda environment when spawned and should not be in the lambda's package.json but when invoking locally node must resolve it's location
  • one way to go around this is to install it as a dev-dependency and make sure to npm install --production before lambda deployment.
  • another way is to wrap your repository project directory in another parent folder and install the aws-sdk in this parent folder (that is not comited on your repository).

You are ready to use it in Quick Invoke mode! (see steps to use)

Additional steps required for SAM CLI mode:

• install sam-cli
• make sure Docker is running (should already have it installed from previous step)

You are ready to use it in SAM CLI mode! (see steps to use)

Steps to use:

1. create a folder to store .json event files
2. in this folder, create a .json file for each event you will want to invoke your lambda with
3. in this folder, create a .quick_invoke file and configure the following:
   • name - a group name that will be created for the events in this folder
   • lambdaPath - relative path (from the .quick_invoke file) to the lambda file you want to invoke (.js or .ts) -- (see using with typescript section)
   • tsconfigPath (optional) - relative path to a tsconfig.json to use when compiling ts files
   • registers (string) - change node registers on invoked functions eg: esbuild-register or ts-node/register,tsconfig-paths/register
   • exportName - the handler name of the exported fuction in the lambda
     • ex: if you have module.exports.handler = function(event,.. name should be handler
   • variablesPath (optional) - relative path to the json file that holds the environment parameters your lambda uses
   • variablesRootKey (optional) - the name of the Key that holds the env variables from the variables json file
     • (!) important: on SAM CLI mode this value should also be the name of the lambda as configured in the template (both for manual templates or templates generated by the cdk)
   • template (required on SAM CLI mode) - relative path to the .yaml / .json CF template
4. open Quick invoke tab from the left side menu and you should see the list of events (use manual refresh if needed)
5. use the play button next to each event to invoke the lambda (this will open a terminal and run the command)
6. use the re-play last invokation button from the status bar to invoke the last lambda again
7. use the Search File to Quick Invoke command (keybinding ALT + SHIFT + P - name: "quick.invoke.search.to.invoke" ) to quickly select:
   • an event with the same file name as the opened file in the text editor
   • an event from the history of invocations
   • an event that fuzzy-matches a query string

Using with Typescript:

There are 2 ways to use Quick Invoke with a Typescript project:

1. set lambdaPath to a .js file within your compiled output folder (like: dist | lib | out)
   • compile the project source before each invocation (either manually or with tsc -w)
2. set lambdaPath to a .ts file from your typescript source code
   • the code will be compiled at invocation time using ts-node as the node register
   • in this case, you should also specify the tsconfigPath in the .quick_invoke file
   • in this case it is a requirement to have ts-node installed globally

Configuring node registers

For Typescript, the legacy and default register is ts-node but you can use other registers like esbuild-register (recommended) by providing the registers key in the .quick_invoke config file.

Other Configurations:

From the Configuration view you can change the following:

• choose the AWS Profile to use when running your lambda code (affects all aws-sdk frameworks used by the lambda)
• turn debug mode on/off - debug mode attaches a debugger and allows usage of VS Code breakpoints and inspect tools
• continueOnAttach - by default using debug mode will stop on entry of the file
• change between Quick Invoke vs SAM CLI invokation modes

Quick Invoke mode vs SAM CLI mode

This tool has been created with Quick Invoke mode as a main usage in mind.

If you are not using Node.js as your Lambda Environment or if you preffer using Docker you can use the SAM CLI mode.

SAM CLI mode has been tested to work both with manually created Cloud Formation templates and with templates generate by cdk synth --no-staging.

Known issues:

• TypeScript does not find module with custom path and throws "Error: Cannot find module xxx"
  • override the registers with either: ts-node/register,tsconfig-paths/register or esbuild-register (recommended)
  • note that you will have to install the registers as devDependencies
• SAM CLI is not compatible with lerna.
  • details: sam cli will not copy the symlinked folders from node_modules
  • woraround: use Quick Invoke mode in this case.
• SAM cli uses the permission your aws iam user has and does not use the permissions defined in the template
• running with Quick Invoke mode with debug mode on will open a file named [eval] - just ignore it

Running on Windows:

• works only if you have gitbash shell installed and configured as default Shell in VS Code