OSLS (Open-Source Serverless) Framework

3.63.2 · active · verified Tue Apr 21

OSLS (Open-Source Serverless) Framework, currently at version 3.63.2, is a community-maintained, open-source fork of the Serverless Framework v3. It acts as a drop-in replacement for users who cannot or choose not to upgrade to Serverless Framework v4. The project primarily focuses on supporting AWS Lambda deployments, offering up-to-date compatibility with new AWS runtimes and bug fixes. It distinguishes itself by being lighter and faster than the original v3, having removed enterprise features (like Serverless Dashboard and Components), auto-updating, and unused dependencies. Maintained by the Bref community, its release cadence involves frequent patch and minor updates to ensure continued compatibility and security. It supports various languages including Node.js, TypeScript, Python, Go, and Java, leveraging an approachable YAML syntax for defining serverless applications and their infrastructure.

Common errors

```
serverless: command not found
```
cause The OSLS CLI is not installed globally or is not accessible in your system's PATH.

fix Install OSLS globally using `npm install -g osls`.
```
InvalidParameterValueException: Missing required credentials for this provider.
```
cause AWS credentials are not correctly configured or are not accessible by the OSLS CLI.

fix Configure your AWS credentials using `serverless config credentials --provider aws --key YOUR_AWS_ACCESS_KEY_ID --secret YOUR_AWS_SECRET_ACCESS_KEY`, or ensure environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) or a valid AWS profile are set.
```
YAMLException: bad indentation of a mapping entry (line X, column Y)
```
cause The `serverless.yml` configuration file contains an indentation error, which is critical for YAML parsing.

fix Review the `serverless.yml` file at the specified line and column for incorrect spacing or tabs. YAML requires strict indentation using spaces.

Warnings

breaking OSLS has removed Serverless Dashboard/Enterprise features. Functionality such as monitoring, debugging, and collaboration tools previously available in the Serverless Dashboard are no longer supported.
Fix: Migrate to Serverless Framework v4 if these features are critical to your workflow, or explore third-party monitoring and management solutions for your serverless applications.
breaking Support for Serverless Components has been entirely removed in OSLS. Projects relying on Serverless Components will not be deployable with this framework.
Fix: Refactor your application to use standard Serverless Framework resources, cloud provider-native constructs (e.g., CloudFormation), or alternative infrastructure-as-code tools.
gotcha OSLS does not automatically use local `serverless` installations found in `node_modules`. It explicitly removes this behavior to prevent accidental execution of different versions.
Fix: Ensure OSLS is installed globally using `npm install -g osls`. Always invoke commands directly via `serverless <command>` after global installation.
gotcha OSLS is primarily maintained and optimized for AWS Lambda deployments. While the original Serverless Framework supported multiple cloud providers, OSLS's focus is on AWS, with documentation and features tailored for it.
Fix: Users targeting other cloud providers (e.g., Azure, Google Cloud, Apache OpenWhisk) should use the original Serverless Framework v4 or provider-specific serverless deployment tools.

Install

npm install osls npm
yarn add osls yarn
pnpm add osls pnpm

Imports

serverless (CLI)
wrong:
```
npm install osls
serverless deploy
```
correct:
```
npm install -g osls
serverless deploy
```
OSLS is intended for global installation and direct command-line execution, replacing the original `serverless` CLI. Local installations are not automatically picked up unless using `npx` or explicit path.
ServerlessConfig (type)
wrong:
```
import { ServerlessConfig } from 'osls';
```
correct:
```
import type { ServerlessConfig } from 'osls';
```
Used for type-checking `serverless.yml` configurations or for programmatic generation of service configurations within TypeScript projects.
Serverless (class)
wrong:
```
const Serverless = require('osls');
import Serverless from 'osls';
```
correct:
```
import { Serverless } from 'osls';
```
This class is primarily used for developing custom plugins, allowing programmatic interaction with the framework's core instance, logging, and configuration within a plugin context.

Quickstart

This quickstart demonstrates how to install OSLS globally, define a basic AWS Lambda function with an API Gateway endpoint using `serverless.yml`, deploy it, invoke it, and then remove the deployed resources.

// serverless.yml
service: my-first-osls-app
frameworkVersion: "3"

provider:
  name: aws
  runtime: nodejs20.x
  region: us-east-1
  stage: dev

functions:
  hello:
    handler: handler.hello
    events:
      - httpApi:
          path: /hello
          method: get

// handler.js
'use strict';

module.exports.hello = async (event) => {
  return {
    statusCode: 200,
    body: JSON.stringify(
      {
        message: 'Hello from OSLS!',
        input: event,
      },
      null,
      2
    ),
  };
};

// --- Terminal Commands ---
npm install -g osls
# Navigate to your project directory
# cd my-first-osls-app
serverless deploy --verbose
# Note the endpoint URL from the deploy output
serverless invoke --function hello --log
serverless remove

view raw JSON →