mirror of
https://github.com/serverless/serverless.git
synced 2026-01-18 14:58:43 +00:00
103 lines
4.2 KiB
Markdown
103 lines
4.2 KiB
Markdown
# JAWS: Create reusable modules
|
|
|
|
Reusable AWSM modules can be distributed to the community by publishing an NPM
|
|
package. This guide is meant to help developers to get up & running with publishing
|
|
their own modules to NPM, Node's package manager. In the future, support for other platforms will be
|
|
added for which platform-specific guides will be written.
|
|
|
|
A typical NPM package will have the following structure:
|
|
|
|
```
|
|
/awsm
|
|
/moduleName
|
|
/functionName
|
|
/lib
|
|
/something
|
|
awsm.json
|
|
```
|
|
|
|
The most important things to be aware of:
|
|
|
|
* The `/awsm` directory is meant as a scaffolding folder for [AWSM](https://github.com/awsm-org/awsm) modules.
|
|
This means that the content of this folder will be replicated to the project's `aws_modules`
|
|
folder once the module is installed. Be aware that updates to this folder in your package
|
|
do not propagate to projects which have installed the module before, because the projects contain
|
|
their own copy of the AWSM module.
|
|
|
|
* The `/lib` directory is the folder for your reusable and versioned code. This means
|
|
the content of this folder cannot be touched by the implementer and will be
|
|
automatically updated when you release a new module version.
|
|
|
|
An important thing to know is that you can only access your module's dependencies from
|
|
within the `lib` folder. This might sound as a limitation, but this is actually a good thing
|
|
since this enforces a clean separation of your module logic and implementation.
|
|
|
|
For a working example, have a look at the [awsm-images](https://github.com/awsm-org/awsm-images) module.
|
|
|
|
## Creating a new NPM module
|
|
|
|
The steps needed for creating your own NPM module:
|
|
|
|
* Create a new project directory (example: `/awsm-users`) for your module, outside of any existing project directories.
|
|
|
|
* Switch to the module directory, create `/awsm` and `/lib` directories and put your initial module files in there.
|
|
|
|
* Add a file called `awsm.json` in the root of the module with the following content:
|
|
|
|
```
|
|
{
|
|
"name": "awsm-users",
|
|
"version": "0.0.1",
|
|
"location": "https://github.com/...",
|
|
"author": "",
|
|
"description": "",
|
|
"resources": {
|
|
"cloudFormation": {
|
|
"LambdaIamPolicyDocumentStatements": [],
|
|
"ApiGatewayIamPolicyDocumentStatements": [],
|
|
"Resources": {}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Replace the `name`, `location`, `author` and `description` attributes with the correct values.
|
|
|
|
* Run `npm init` to generate a [package.json](https://docs.npmjs.com/files/package.json) file.
|
|
|
|
* Install any dependencies by using `npm install --save <dependency>`. Same goes for devDependencies (use `--save-dev` here).
|
|
|
|
* Add the following `postinstall` configuration to the `scripts` section in `package.json` (don't forget to replace the module name):
|
|
|
|
```json
|
|
{
|
|
"scripts": {
|
|
"postinstall" : "jaws postinstall <module-name> npm"
|
|
}
|
|
}
|
|
```
|
|
|
|
This command will perform all tasks needed directly after installing the package, which are:
|
|
* Trigger the replication of your `/awsm` directory to the project's `/aws_modules` directory
|
|
* Merge the CloudFormation configuration into your project
|
|
|
|
* Run `npm link` to create a globally-installed symbolic link to your module. In case you run into permission problems, it might be needed to run this as a superuser (using `sudo` on Linux/OSX).
|
|
|
|
Now, your module is ready to be used in your local projects.
|
|
|
|
## Using the module in your projects
|
|
|
|
While you develop your module locally, it's pleasant to have a project to implement and test it in.
|
|
With the following steps, you can install the module in your project after which it can be tested.
|
|
|
|
* Switch to the project in which you want to install your NPM module.
|
|
|
|
* Run `npm link <module-name>` to create a link in your project's `/node_modules` directory to the globally-installed link.
|
|
|
|
* Run `jaws postinstall <module-name> npm` to execute the `postinstall` command (since `npm link` skips the `postinstall` script).
|
|
|
|
Now your module is installed!
|
|
|
|
Please note that the module is not yet published to the NPM registry and therefore not yet added to your project's package.json.
|
|
Read more about this in the NPM documentation on [publishing NPM packages](https://docs.npmjs.com/getting-started/publishing-npm-packages).
|