@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

npm install @microfox/serverless-yml
# or
yarn add @microfox/serverless-yml

Usage

Validation

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

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.

Mutation

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

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:

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.

config.serverless.json Structure

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:

{
  "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:

{
  "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:

{
  "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.