npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@inizioevoke/evosynth

v3.1.2

Published

`evosynth` is an [AWS CDK](https://docs.aws.amazon.com/cdk/) utility built on `@aws-cdk/toolkit-lib`. It ships as:

Readme

@inizioevoke/evosynth

evosynth is an AWS CDK utility built on @aws-cdk/toolkit-lib. It ships as:

  • a CLI (evosynth) that synthesizes and deploys CDK apps driven by plain config files (evosynth.ts), so individual projects don't need their own CDK app.ts entrypoint, and
  • a library of typed CDK stacks, constructs, and service helpers (CloudFront, S3, API Gateway, Lambda, CodePipeline/CodeBuild, Route53, SES, SSM, WAF, magic-link passwordless auth, etc.) that those apps are built from.

This document covers installation and CLI usage, and how to write/configure evosynth.ts config files. A deeper reference for individual stacks, services, and constructs will follow in docs/stacks and docs/services.

Requirements

  • Node.js >= 20
  • AWS credentials available via the standard credential chain, or an AWS CLI profile passed with --profile
  • An AWS account/region already set up for CDK (bootstrapped) if you intend to deploy

Installation

Install as a dev dependency of the project you want to deploy:

npm install --save-dev @inizioevoke/evosynth

This gives you the evosynth binary (runnable via npx evosynth ...) plus the typed exports used from your config file (mergeConfigs, WebStaticServerlessAppConfig, DeepPartial, etc.).

CLI usage

npx evosynth <command> [env] [--profile <profile>] [--config <path>] [--app <path>]

Commands

| Command | Description | | --- | --- | | synth | Synthesize the CDK app without deploying | | deploy | Deploy the stack(s) to AWS | | diff | Show the diff between the deployed stack and the local config | | drift | Detect infrastructure drift against the deployed stack | | rollback | Roll back a failed/in-progress deployment | | destroy | Destroy the deployed stack(s) (prompts for y/N confirmation first) |

env

env is an optional positional argument identifying which environment to load from your evosynth config (e.g. dev, uat, prod). If omitted, it defaults to "default" — see Single file below for what that means in practice.

--profile

Pass --profile <name> to deploy/synth using a named AWS CLI profile. When set, it's assigned to AWS_PROFILE for the duration of the command. If omitted, the default AWS credential chain is used (environment variables, default profile, instance role, etc.).

--config

Pass --config <path> to load a specific config file instead of auto-discovering one in the project root (see resolution order). <path> is resolved relative to the current working directory. The filename still determines how it's interpreted: a name with an <env> segment (e.g. some.dev.ts) behaves like a per-environment file and calls its default export; otherwise it behaves like a single file and calls the export named after env.

--app

Pass --app <path> to run a custom app script instead of an evosynth config file. <path> can be a file, or a directory — in which case its index.{ts,mts,js,mjs,cjs} is used (e.g. --app ./stacks/my-project runs ./stacks/my-project/index.ts). Use this when you need to build your own stacks rather than describe a web-static-serverless app. [env] and --config are ignored. --profile and the destroy confirmation still apply.

The script's default export is called with the command (deploy, synth, ...). Return an EvosynthApp and the CLI runs the command for you:

// stacks/my-project.ts
import { EvosynthApp } from '@inizioevoke/evosynth/app';
import { App, Stack } from '@inizioevoke/evosynth/aws/core';
import { StringParameterFactory } from '@inizioevoke/evosynth/ssm';

export default async function () {
  return EvosynthApp.create('my-project', async (app: App) => {
    const stack = new Stack(app, 'my-project', { description: 'My Project Common' });
    StringParameterFactory.create(stack, 'web-basicauth-param', {
      parameterName: '/evosynth/web/security/basicauth/my-project',
      stringValue: 'dXNlcjpwYXNzd29yZA=='
    });
  });
}
npx evosynth deploy --app ./stacks/my-project.ts --profile evoke

If the function returns nothing, the CLI assumes the script ran the command itself, e.g. export default async (cmd: CdkCommand) => { const e = await EvosynthApp.create(...); await e[cmd](); }.

Examples

npx evosynth synth dev --profile evoke
npx evosynth deploy dev --profile evoke
npx evosynth diff uat --profile evoke
npx evosynth destroy dev --profile evoke
npx evosynth deploy dev --config ./config/evosynth.dev.ts
npx evosynth deploy --app ./stacks/my-project.ts --profile evoke

Configuration files

Config files live in the root of your project and are named evosynth[.<env>].{js,cjs,mjs,ts,mts}. A leading dot (.evosynth[.<env>].{js,cjs,mjs,ts,mts}) is also supported, if you'd rather keep the config file out of the way. The CLI loads tsx on the fly to run TypeScript files directly — no separate build/compile step is required.

Each config file resolves to one or more EvosynthAppProps objects (e.g. WebStaticServerlessAppConfig), which the CLI feeds into the matching stack factory (currently web-static-serverless and str8r-clm both resolve to the static-serverless web stack).

There are two supported layouts — pick whichever fits the project. They can also be mixed (see resolution order).

Single file

One evosynth.ts file for every environment, exporting one async function per environment named after the environment:

// evosynth.ts
import { mergeConfigs, type WebStaticServerlessAppConfig, type DeepPartial } from '@inizioevoke/evosynth';

const config = {
  appType: 'web-static-serverless',
  appName: 'my-project',
  appDescription: 'My Project',
  envType: 'NOT_PROD',
  region: 'us-east-1',
  tags: {
    Account: 'Account Name',
    Brand: 'Brand Name'
  },
  dns: {
    zone: 'evosynth.inzevo.net'
  }
} satisfies DeepPartial<WebStaticServerlessAppConfig>;

export async function dev(): Promise<WebStaticServerlessAppConfig> {
  return mergeConfigs(config, {
    envName: 'dev',
    dns: { record: 'my-project.dev.client.evosynth.inzevo.net' }
  });
}

export async function uat(): Promise<WebStaticServerlessAppConfig> {
  return mergeConfigs(config, {
    envName: 'uat',
    dns: { record: 'my-project.uat.client.evosynth.inzevo.net' }
  });
}

Running npx evosynth deploy dev calls the exported dev() function. mergeConfigs is a small deep-merge helper for layering environment-specific overrides on top of a shared base config — it's entirely optional; each exported function just needs to return a complete EvosynthAppProps-shaped object (or an array of them, if the file manages multiple apps/stacks). Declaring the base with satisfies (rather than a DeepPartial<...> type annotation) keeps its real shape, and leaving off the generic on mergeConfigs lets it infer the merged result — that combination is what makes a missing required field or a typo'd value show up as an editor error on dev()'s Promise<WebStaticServerlessAppConfig> return type, instead of silently passing.

If you run a command without an env argument, the CLI looks for an export literally named default — i.e. a standard export default async function() { ... }. This is what lets a single-file config support a no-argument invocation (npx evosynth deploy) if you want one.

Per-environment files

One file per environment, named evosynth.<env>.ts, each with a default export (the environment name only lives in the filename, not the export name):

// evosynth.dev.ts
import { type WebStaticServerlessAppConfig } from '@inizioevoke/evosynth';

export default async function(): Promise<WebStaticServerlessAppConfig> {
  return {
    appType: 'web-static-serverless',
    appName: 'my-project',
    appDescription: 'My Project',
    envType: 'NOT_PROD',
    envName: 'dev',
    region: 'us-east-1',
    dns: {
      record: 'my-project.dev.client.evosynth.inzevo.net',
      zone: 'evosynth.inzevo.net'
    }
  };
}
// evosynth.prod.ts
export default async function(): Promise<WebStaticServerlessAppConfig> {
  // ...
}

Running npx evosynth deploy prod loads evosynth.prod.ts and invokes its default export.

Resolution order

For a given env (or "default" if none was passed), the CLI:

  1. Looks in the project root for any file matching evosynth[.<name>].{js,cjs,mjs,ts,mts} (a leading dot is also matched).
  2. Prefers a per-environment file whose <name> matches env (case-insensitive) and calls its default export.
  3. Otherwise falls back to the single, no-suffix evosynth.ts file and calls the export named after env (e.g. dev, uat, or default).
  4. If no matching file/export is found, the CLI logs an error and exits non-zero.

destroy confirmation

destroy always prompts Are you sure you want to destroy the "<env>" environment? (y/N) (or ... the app "<path>"? (y/N) with --app) before doing anything — only y/yes proceeds.

Configuration

Whatever shape your evosynth.ts export(s) return, it needs to resolve to an EvosynthAppProps object (e.g. WebStaticServerlessAppConfig) — or an array of them, if one file deploys multiple apps/stacks. The top-level shape is:

| Key | Type | Required | Notes | | --- | --- | --- | --- | | appType | 'web-static-serverless' \| 'str8r-clm' | yes | Selects which stack factory builds the app. Both values currently route to the same static-serverless web stack. | | appName | string | yes | Used for logging and typically for naming/tagging resources. | | appDescription | string | yes | Human-readable description. | | envType | 'NOT_PROD' \| 'PROD' | yes | Broad environment classification (used for things like removal policy defaults, not the same as envName). | | envName | string | yes | The specific environment name (dev, uat, prod, ...). By convention this matches the env CLI argument / config filename segment, but it's a separate field you set explicitly. | | region | string (e.g. 'us-east-1') | yes | The AWS region to deploy into. | | tags | Record<string, string> | no | Applied to resources; Account and Brand are the conventional keys, but any string key is allowed. | | destroy | boolean | no | See Removal policy vs. the destroy command below. | | s3 | S3BucketProps | no | { bucketName?, destroy? } | | dns | DnsProps | no | { record: string \| string[], zone: string, external?: boolean } | | cloudfront | DistributionProps | no | CloudFront distribution config — see CloudFront below. | | passwordless | PasswordlessProps | no | Magic-link passwordless-auth construct config — see Passwordless auth below. | | codePipeline | PipelineFactoryProps | no | CI/CD pipeline config — see CodePipeline below. |

Conventions that show up throughout these nested objects:

Literal value vs. SSM parameter

Many fields come in a pair: a literal value, and a ...Param variant that reads the value from SSM Parameter Store at synth/deploy time instead. The parameter form accepts either a bare path string or an object with an optional version:

type SsmStringParameter = { path: string; version?: number };

For example cloudfront.webAclParam, cloudfront.defaultBehavior.auth.credentialsParam, and codePipeline.stages.source.codestarConnectionParam all accept string | SsmStringParameter. Prefer the ...Param form for anything account-specific or secret so it isn't hard-coded into the config file.

Mutually-exclusive option groups

Some fields are "pick exactly one (or at least one) of these sibling keys" groups, enforced at the type level (AllowOnlyOne / RequireAtLeastOne) rather than with a discriminant property. For example a CodeBuild image is chosen via exactly one of buildImage, buildImageId, buildImageNodeJS, or buildImageEcr. TypeScript will flag it if you set more than one.

RequireAtLeastOne groups only enforce that you made a choice among the sibling keys — not that the choice enables anything. cloudfront's WAF fields (webAcl, webAclParam, webAclProps) are one such group: you must set one of them, but webAcl: false is itself a valid, explicit choice meaning "no WAF." That's intentional — it forces every config to state its WAF posture rather than silently defaulting to none.

Removal policy vs. the destroy command

The config-level destroy?: boolean flag (available on the app config itself, and on sub-configs like s3 and passwordless) is not the same thing as running npx evosynth destroy. It controls the CDK removal policy for that resource — true applies RemovalPolicy.DESTROY (deleted when the stack/resource is removed), omitted/false applies RemovalPolicy.RETAIN (kept around, e.g. to avoid losing an S3 bucket or DynamoDB table on a stack teardown). Set it deliberately per environment — e.g. destroy: true for dev, left unset for prod.

Region and account

region comes from your config. The AWS account, however, is never read from the config file — it's resolved from whichever credentials/profile the command runs with (CDK_DEFAULT_ACCOUNT, populated from the AWS credential chain or the --profile you passed). This keeps the same config portable across accounts (e.g. a dev account vs. a prod account) as long as --profile (or the active credentials) points at the right one.

CloudFront

cloudfront requires you to set one of webAcl, webAclParam, or webAclProps (top-level fields, independent of defaultBehavior) — see Mutually-exclusive option groups. Set webAcl to an ARN to attach an existing Web ACL, webAclParam to read one from SSM, webAclProps to create a new one, or webAcl: false to explicitly opt out of WAF entirely. defaultBehavior itself is optional — if omitted (or if defaultBehavior.origin is omitted), evosynth creates an S3 bucket and uses it as the default origin. A behavior's auth can be { type: 'basic', credentials | credentialsParam }, { type: 'passwordless' } (wired to the passwordless construct below), or { type: 'sso' }. Redirects are configured per default-behavior via redirects: { trailingSlash?: 'add' | 'remove', rules: string | HttpRedirectRule[] }, where rules can be an inline array of { match, redirect, status?, query? } or a string (e.g. the contents of a CSV read at config-build time, as in samples/redirects.ts). match can be an exact path (/old), a *-wildcard path prefix (/hello*), or the literal '*', which is a catch-all matched only if no exact or wildcard rule matches the request — useful for redirecting every path on a distribution (see Redirecting a whole domain below). status defaults to 301; query defaults to appending the original querystring to redirect and must be set to false to suppress that. Full coverage of origins, behaviors, functions, caching/response-header policies, and error responses will land in docs/services.

CodePipeline

codePipeline.stages.source wires a CodeStar connection (codestarConnectionArn or codestarConnectionParam) plus owner/repo/branch to pull source from Bitbucket/GitHub. codePipeline.stages.build.codebuild configures the CodeBuild project, including which build image to use (buildImage / buildImageId / buildImageNodeJS / buildImageEcr — pick one) and an optional inline buildSpec. See the sample config at the top of this document and samples/codebuild/ for a working buildspec.

Passwordless auth

passwordless configures a magic-link login flow gated entirely by CloudFront signed cookies — there's no Cognito or user pool involved. A visitor hits an /request-access page, enters an allow-listed email (checked against passwordless.allow, protected by reCAPTCHA), and receives an emailed link (via SES) to an /authenticate endpoint. That endpoint validates the link and sets CloudFront signed cookies (CloudFront-Policy/-Signature/-Key-Pair-Id) using a CloudFront key pair generated and stored in SSM, scoped to the whole site domain. All other CloudFront behaviors are restricted to that trusted key group, so unauthenticated requests get a 403 that's rewritten back to /request-access. request-access/authenticate are implemented as Lambda functions behind an API Gateway HTTP API, invoked as additional CloudFront behaviors on the two paths, with access attempts logged to a DynamoDB table. It's one of the larger sub-configs — a full field-by-field reference will follow in docs/services alongside the CloudFront auth: { type: 'passwordless' } wiring.

Redirecting a whole domain

Since each exported function can resolve to an array of EvosynthAppProps instead of a single one (see Single file), one evosynth.ts can deploy two separate app/stack pairs from the same file: the real site, plus a second, minimal CloudFront distribution bound to another domain whose only job is to redirect every request on it over to the first domain — e.g. domain.com → www.domain.com, or vice versa. The second entry needs its own dns.record (the domain being redirected from) and a catch-all redirect rule (match: '*', see CloudFront above) pointed at the primary domain:

export default async function(): Promise<WebStaticServerlessAppConfig[]> {
  return [
    mergeConfigs(config, {
      envName: 'prod',
      envType: 'PROD',
      dns: { record: 'www.example.com' }
    }), {
      // Redirect example.com => www.example.com
      appType: 'web-static-serverless',
      appName: 'my-project-domain-redirect',
      appDescription: 'My Project Domain Redirect',
      envType: 'PROD',
      envName: 'prod',
      region: 'us-east-1',
      tags: { Account: 'Account Name', Brand: 'Brand Name' },
      dns: {
        record: 'example.com',
        zone: 'example.com'
      },
      cloudfront: {
        webAclParam: '/evosynth/web/security/webacl',
        defaultBehavior: {
          redirects: {
            rules: [{ match: '*', redirect: 'https://www.example.com' }]
          }
        }
      }
    }
  ];
}

The redirect itself works at the path level (a CloudFront Function checks the request URI against rules), not by inspecting the Host header — it's the second app's own dns.record/CloudFront distribution that makes the redirect apply to that domain, and the '*' rule is a last-resort match that fires for literally any path on it since no earlier rule claims it. See the commented-out array return at the bottom of test/basic/.evosynth.ts for a working version of this pattern.

Full example

Putting it all together — a single-file config (see Single file) using mergeConfigs to layer a dev and prod environment on a shared base, exercising s3, dns, cloudfront (with basic auth, CSP headers, and redirects), and codePipeline:

// evosynth.ts
import { mergeConfigs, type WebStaticServerlessAppConfig, type DeepPartial } from '@inizioevoke/evosynth';

const config = {
  appType: 'web-static-serverless',
  appName: 'my-project',
  appDescription: 'My Project',
  envType: 'NOT_PROD',
  region: 'us-east-1',
  tags: {
    Account: 'Account Name',
    Brand: 'Brand Name'
  },
  dns: {
    zone: 'evosynth.inzevo.net'
  },
  cloudfront: {
    webAclParam: '/evosynth/web/security/webacl',
    defaultBehavior: {
      auth: {
        type: 'basic',
        // credentials: 'dXNlcjpwYXNzd29yZA==',
        credentialsParam: '/evosynth/my-project/security/basicauth'
      },
      // cspHeaders: // read in a csv and set as a string
      cspHeaders: {
        "'self'": [
          'default-src',
          'connect-src',
          'script-src',
          'style-src'
        ],
        "'unsafe-inline'": [
          'style-src'
        ]
      },
      redirects: {
        trailingSlash: 'add',
        // rules: '' // read in a csv and set as a string
        rules: [
          { match: '/old', redirect: '/new/' }
        ]
      }
    }
  },
  codePipeline: {
    stages: {
      source: {
        codestarConnectionParam: '/evosynth/bitbucket/codeconnection',
        owner: 'evokegroup',
        repo: 'my-project'
      },
      build: {
        codebuild: {
          buildImageNodeJS: 24
        }
      }
    }
  }
} satisfies DeepPartial<WebStaticServerlessAppConfig>;

// dev environment — disposable, so destroy: true everywhere
export async function dev(): Promise<WebStaticServerlessAppConfig> {
  return mergeConfigs(config, {
    envName: 'dev',
    dns: { record: 'my-project.dev.client.evosynth.inzevo.net' },
    codePipeline: { stages: { source: { branch: 'develop' } } }
  });
}

// prod environment — override envType and flip destroy flags to retain resources
export async function prod(): Promise<WebStaticServerlessAppConfig> {
  return mergeConfigs(config, {
    envType: 'PROD',
    envName: 'prod',
    destroy: false,
    s3: { destroy: false },
    dns: { record: 'my-project.example.com' },
    codePipeline: { stages: { source: { branch: 'main' } } }
  });
}
npx evosynth deploy dev --profile evoke
npx evosynth deploy prod --profile evoke

See samples/evosynth.ts and samples/evosynth.env.ts for more runnable starting points, and samples/redirects.ts/samples/csp.ts for loading redirects/CSP rules from a CSV at config-build time instead of inlining them.

What's next

Stacks (e.g. web-static-serverless), the service helpers (cloudfront, s3, route53, codepipeline, codebuild, apigateway, lambda, dynamodb, ses, ssm, waf, certmgr), and constructs (e.g. passwordless) each have their own config shape layered into the app config shown above (cloudfront, dns, codePipeline, etc.). Those will be documented in detail separately in docs/stacks and docs/services.