Serverless ARN Prefixer Plugin

A Serverless Framework plugin that automatically injects custom ARN properties into your serverless configuration, making it easier to build AWS resource ARNs consistently across your application. Supports both ${arn:*} variable resolvers and ${arn:*} object references for maximum compatibility.

Installation

From npm (Recommended)

npm install @hyperdrive.bot/serverless-arn-prefixer

From GitLab Package Registry (Development)

# Configure npm to use GitLab registry for @hyperdrive.bot scope
npm config set @hyperdrive.bot:registry https://gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/

# Install the package
npm install @hyperdrive.bot/serverless-arn-prefixer

Local Development

If developing within the monorepo, no separate installation required.

Usage

Add the plugin to your serverless.yml:

When installed from npm

plugins:
  - "@hyperdrive.bot/serverless-arn-prefixer"

When using locally in monorepo

plugins:
  - ./packages/serverless/arn-prefixer

Or if using from within the packages/serverless directory:

plugins:
  - ./arn-prefixer

Configuration

Runtime Code Generation (Default: Enabled)

Configure runtime file generation in your serverless.yml:

custom:
  arnPrefixer:
    generateRuntime: true     # Default: true - Enable/disable runtime generation
    runtimePath: 'runtime.js' # Default: 'runtime.js' - Output filename

Disable Runtime Generation:

custom:
  arnPrefixer:
    generateRuntime: false

Custom Runtime Path:

custom:
  arnPrefixer:
    runtimePath: 'my-arn-values.js'  # Will also generate my-arn-values.d.ts

What it does

The plugin automatically injects a custom.arn object into your serverless configuration with the following properties:

NEW: ⚡ Runtime Code Generation (Default: Enabled)

The plugin now generates runtime JavaScript and TypeScript files that allow you to import ARN values directly in your Lambda code without environment variables:

// Import specific values
import { arnPrefix, globalPrefix, dynamodb } from 'arn-prefixer/runtime'

// Use in your Lambda code
const tableName = `${arnPrefix}-users`
const tableArn = `${dynamodb}:table/${tableName}`

This provides zero runtime overhead - values are hardcoded strings at build time!

Basic Properties

custom:
  arn:
    accountId: "123456789012"           # AWS Account ID (from AWS_ACCOUNT_ID env var or STS)
    stage: "dev"                        # Serverless stage
    service: "my-service"               # Serverless service name
    region: "us-east-1"                 # AWS region
    prefix: "my-service-dev"            # service-stage
    regionalPrefix: "us-east-1-my-service-dev"        # region-service-stage
    globalPrefix: "123456789012-us-east-1-my-service-dev"  # accountId-region-service-stage

ARN Builder Properties

custom:
  arn:
    # Generic ARN components
    arnBase: "arn:aws"                  # AWS ARN base
    accountRegion: "123456789012:us-east-1"    # accountId:region
    
    # Service-specific ARN bases
    dynamodb: "arn:aws:dynamodb:123456789012:us-east-1"      # DynamoDB ARN base
    s3: "arn:aws:s3:123456789012:us-east-1"                  # S3 ARN base
    lambda: "arn:aws:lambda:123456789012:us-east-1"          # Lambda ARN base
    iam: "arn:aws:iam:123456789012:us-east-1"                # IAM ARN base
    sns: "arn:aws:sns:123456789012:us-east-1"                # SNS ARN base
    sqs: "arn:aws:sqs:123456789012:us-east-1"                # SQS ARN base
    apigateway: "arn:aws:apigateway:123456789012:us-east-1"  # API Gateway ARN base
    events: "arn:aws:events:123456789012:us-east-1"          # EventBridge ARN base
    logs: "arn:aws:logs:123456789012:us-east-1"              # CloudWatch Logs ARN base
    kinesis: "arn:aws:kinesis:123456789012:us-east-1"        # Kinesis ARN base
    firehose: "arn:aws:firehose:123456789012:us-east-1"      # Firehose ARN base
    stepfunctions: "arn:aws:states:123456789012:us-east-1"   # Step Functions ARN base

Using the injected values

Once the plugin is loaded, you can reference these values anywhere in your serverless.yml using two methods:

Method 1: Variable Resolver

Use the ${arn:property} syntax:

resources:
  Resources:
    MyDynamoDBTable:
      Type: AWS::DynamoDB::Table
      Properties:
        TableName: ${arn:prefix}-users
        # Results in: my-service-dev-users

    MyS3Bucket:
      Type: AWS::S3::Bucket
      Properties:
        BucketName: ${arn:globalPrefix}-assets
        # Results in: 123456789012-us-east-1-my-service-dev-assets

functions:
  myFunction:
    name: ${arn:regionalPrefix}-handler
    # Results in: us-east-1-my-service-dev-handler

Method 2: Custom Object (Manual Definition Required)

Use the ${arn:property} syntax (requires manual property definition):

resources:
  Resources:
    MyDynamoDBTable:
      Type: AWS::DynamoDB::Table
      Properties:
        TableName: ${arn:prefix}-users
        # Results in: my-service-dev-users

functions:
  myFunction:
    name: ${arn:regionalPrefix}-handler
    # Results in: us-east-1-my-service-dev-handler

⚠️ Important Compatibility Notes:

• Method 1 (${arn:*}): ✅ Works with this plugin - uses custom variable resolvers
• Method 2 (${arn:*}): ❌ Cannot work with plugin-injected properties in Serverless v2 due to variable resolution timing

Why Method 2 Doesn't Work With Plugin

Serverless v2 resolves ALL variables BEFORE loading plugins. This means:

1. ${arn:*} tries to resolve during YAML parsing
2. Plugin hasn't loaded yet, so no custom.arn properties exist
3. Resolution fails and stops the process

When Method 2 DOES Work

${arn:*} works when properties are statically defined in serverless.yml:

custom:
  arn:
    accountId: ${env:AWS_ACCOUNT_ID, '123456789012'}
    prefix: ${self:service}-${self:provider.stage}
    # ... other properties defined manually

Recommendations

• With this plugin: Use Method 1 (${arn:*}) syntax
• With serverless-plugin-composer: Define custom.arn manually and use Method 2 (${arn:*})
• Hybrid approach: Define basic properties manually, let plugin handle complex ARN building

Method 3: Runtime Imports (NEW! ⚡ Zero Runtime Overhead)

Import ARN values directly in your Lambda code:

// ES6 imports
import { arnPrefix, globalPrefix, dynamodb, s3 } from 'arn-prefixer/runtime'

// CommonJS
const { arnPrefix, globalPrefix, dynamodb, s3 } = require('arn-prefixer/runtime')

// Use in your Lambda handlers
export const handler = async (event) => {
  const tableName = `${arnPrefix}-users`
  const bucketName = `${globalPrefix}-assets`
  
  // Build complete ARNs
  const tableArn = `${dynamodb}:table/${tableName}`
  const bucketArn = `${s3}:bucket/${bucketName}`
  
  // Your Lambda logic here
}

Available Exports:

• arnPrefix - service-stage (e.g., "my-service-dev")
• globalPrefix - accountId-region-service-stage (e.g., "123456789012-us-east-1-my-service-dev")
• regionalPrefix - region-service-stage (e.g., "us-east-1-my-service-dev")
• All AWS service ARN builders: dynamodb, s3, lambda, sns, sqs, etc.

Method 4: ARN Builders (Serverless Config)

Build complete AWS ARNs easily:

resources:
  Resources:
    # DynamoDB Table ARN
    MyDynamoTable:
      Type: AWS::DynamoDB::Table  
      Properties:
        TableName: ${arn:prefix}-users
      Outputs:
        TableArn:
          Value: ${arn:dynamodb}:table/${arn:prefix}-users
          # Results in: arn:aws:dynamodb:123456789012:us-east-1:table/my-service-dev-users

    # S3 Bucket ARN  
    MyBucket:
      Type: AWS::S3::Bucket
      Properties:
        BucketName: ${arn:globalPrefix}-assets
      Outputs:
        BucketArn:
          Value: ${arn:s3}:bucket/${arn:globalPrefix}-assets
          # Results in: arn:aws:s3:123456789012:us-east-1:bucket/123456789012-us-east-1-my-service-dev-assets

    # Lambda Function ARN
    MyFunction:
      Outputs:
        FunctionArn:
          Value: ${arn:lambda}:function:${arn:prefix}-processor  
          # Results in: arn:aws:lambda:123456789012:us-east-1:function:my-service-dev-processor

# IAM Policy using ARN builders
user-role-statements:
  - Effect: Allow
    Action:
      - dynamodb:GetItem
      - dynamodb:PutItem
    Resource:
      - ${arn:dynamodb}:table/${arn:prefix}-*      # All tables matching pattern
      - ${arn:dynamodb}:table/*/index/*            # All indexes

Common ARN Patterns

# Your specific use cases:
DynamoDBTableArn: ${arn:dynamodb}:table/resource              # arn:aws:dynamodb:account:region:table/resource
DynamoDBAllTablesArn: ${arn:dynamodb}:table/*                # arn:aws:dynamodb:account:region:table/*
S3BucketArn: ${arn:s3}:bucket/${arn:prefix}-bucket          # arn:aws:s3:account:region:bucket/service-stage-bucket
LambdaFunctionArn: ${arn:lambda}:function:${arn:prefix}-func  # arn:aws:lambda:account:region:function:service-stage-func
SNSTopicArn: ${arn:sns}:${arn:prefix}-topic                  # arn:aws:sns:account:region:service-stage-topic
SQSQueueArn: ${arn:sqs}:${arn:prefix}-queue                  # arn:aws:sqs:account:region:service-stage-queue

Comparison with Serverless Framework Defaults

Serverless Framework Default Patterns

| Resource Type | Default Pattern | Example | |---------------|-----------------|---------| | CloudFormation Stack | {service}-{stage} | my-service-dev | | Lambda Functions | {service}-{stage}-{functionName} | my-service-dev-hello | | API Gateway | {stage}-{service} | dev-my-service | | IAM Roles | {service}-{stage}-{region}-lambdaRole | my-service-dev-us-east-1-lambdaRole | | Custom Resources | {LogicalId}-{RandomSuffix} | MyTable-ABC123DEF456 |

ARN-Prefixer Plugin Patterns

| Plugin Variable | Pattern | Example | |----------------|---------|---------| | ${arn:prefix} | {service}-{stage} | my-service-dev | | ${arn:regionalPrefix} | {region}-{service}-{stage} | us-east-1-my-service-dev | | ${arn:globalPrefix} | {accountId}-{region}-{service}-{stage} | 123456789012-us-east-1-my-service-dev |

Key Advantages

• ✅ Consistency: All resources follow the same naming convention
• ✅ Predictability: No random suffixes, deterministic resource names
• ✅ Uniqueness: Account ID inclusion ensures cross-account uniqueness
• ✅ Multi-region: Region awareness for global deployments
• ✅ Enterprise Ready: Suitable for complex, multi-tenant architectures

Account ID Resolution

The plugin will attempt to get the AWS Account ID in the following order:

1. Environment Variable: If AWS_ACCOUNT_ID is set, it will use that value
2. AWS STS: If the environment variable is not set, it will call AWS STS getCallerIdentity() to retrieve the account ID
3. Error: If both methods fail, the plugin will throw an error and stop deployment

Important: You must either set the AWS_ACCOUNT_ID environment variable or have valid AWS credentials configured. The plugin will not proceed with deployment if it cannot determine the AWS Account ID.

Compatibility

Tested Versions

| Serverless Framework | Status | Features Tested | |---------------------|--------|----------------| | 2.72.4 | ✅ Fully Tested | Prefix properties + ARN builders + Error handling | | 3.38.0 | ✅ Fully Tested | Prefix properties + ARN builders + Error handling | | 4.18.2 | ✅ Fully Tested | Prefix properties + ARN builders + Error handling |

Requirements:

• Serverless Framework: 2.0.0 and above (supports v2, v3, and v4)
• Node.js: 14.0.0 and above

Plugin Execution

The plugin runs during the after:aws:common:validate:validate hook, ensuring that all properties are available before your resources are processed.

Example Output

Successful execution:

ARN Prefixer: Injected custom.arn properties
  - accountId: 123456789012
  - stage: dev
  - service: my-service
  - region: us-east-1
  - prefix: my-service-dev
  - regionalPrefix: us-east-1-my-service-dev
  - globalPrefix: 123456789012-us-east-1-my-service-dev

Error when Account ID cannot be determined:

ARN Prefixer Plugin Error: Cannot determine AWS Account ID.

Please either:
1. Set the AWS_ACCOUNT_ID environment variable, or
2. Ensure you have valid AWS credentials configured

AWS STS Error: The security token included in the request is expired