@microfox/serverless-yml

A utility package for validating and mutating serverless.yml files, with a focus on automating configurations for services using @microfox packages.

Features

- Validation: Ensures your serverless.yml follows best practices and required structures.
- Automatic Configuration: Automatically mutates the serverless.yml file to include necessary configurations based on the @microfox packages your service uses.

Installation

``bash
npm install @microfox/serverless-yml


or


yarn add @microfox/serverless-yml
`

Usage

$3

You can validate your serverless.yml content to ensure it's correctly configured.

`typescript
import { validateServerlessYML } from '@microfox/serverless-yml';
import fs from 'fs';

const yamlContent = fs.readFileSync('serverless.yml', 'utf-8');
const { isValid, errors } = validateServerlessYML(yamlContent);

if (!isValid) {
console.error('Serverless YML validation failed:', errors);
}
`

The validateServerlessYML function checks for:

- The presence of a functions section.
- Each function (except getDocs) having events (with at least one http event) and a handler.

$3

The package can automatically apply configurations to your serverless.yml based on the @microfox packages detected in your function files' imports.

`typescript
import { mutateServerlessYML } from '@microfox/serverless-yml';
import fs from 'fs';

// Assume functionFiles is an array of objects describing your function files.
// This is typically generated by analyzing your codebase.
const functionFiles = [
{
fileName: 'handler.ts',
filePath: 'src/handler.ts',
imports: ['@microfox/puppeteer-sls'],
exports: ['myHandler'],
},
];

const yamlContent = fs.readFileSync('serverless.yml', 'utf-8');

// Define a custom mutator if needed (optional)
const myMutator = (yamlContent, functionFiles) => {
// Your custom logic to modify yamlContent
return yamlContent;
};

const newYamlContent = await mutateServerlessYML(
yamlContent,
functionFiles,
myMutator, // This will be applied along with the default packageMutator
);

fs.writeFileSync('serverless.yml', newYamlContent);
`

You can also apply a batch of mutators:

`typescript
import { batchMutateServerlessYML } from '@microfox/serverless-yml';

// ...

const newYamlContent = await batchMutateServerlessYML(
yamlContent,
functionFiles,
[myMutator1, myMutator2], // your custom mutators
);
`

Automatic Configuration with config.serverless.json

When you use a @microfox package (e.g., @microfox/puppeteer-sls), this utility looks for a config.serverless.json file within that package's directory in the @microfox monorepo. It then automatically merges the configurations into your service's serverless.yml.

$3

This file defines how a @microfox package affects the serverless.yml.

- package: Defines packaging configurations.
- provider: Defines provider-level configurations.
- functions: Defines function-level configurations.

#### package

This section is merged with the package section of serverless.yml. Arrays like include and exclude are merged, and duplicates are removed.

Example:

`json
{
"package": {
"include": ["some-file.js"],
"exclude": ["node_modules/unwanted-dep/**"],
"individually": true
}
}
`

#### provider

This section is merged with the provider section of serverless.yml.

Example:

`json
{
"provider": {
"timeout": 60,
"memorySize": 512
}
}
`

#### functions

This section allows modification of all functions in the service. It's useful for adding shared configurations like layers.

Example:

`json
{
"functions": {
"layers": ["arn:aws:lambda:us-east-1:xxxx:layer:my-layer:1"]
}
}
`

Example Workflow

1. A developer adds the @microfox/puppeteer-sls package to their service.
2. In their deployment script or a dedicated tool, they use @microfox/serverless-yml.
3. The tool scans the function files and detects that @microfox/puppeteer-sls is imported.
4. The packageMutator from @microfox/serverless-yml fetches packages/puppeteer-sls/config.serverless.json from the microfox-ai/microfox GitHub repository.
5. The configurations from this JSON file (e.g., provider settings, layers for functions, packaging includes/excludes) are automatically merged into the service's serverless.yml.
6. The final, mutated serverless.yml is used for deployment.

This process simplifies configuration management and ensures consistency across services using the same @microfox` packages.