DEV Community: sudokar

Seamless CJS and ESM: Building Dual-Format Packages with Nx

sudokar — Sun, 26 Oct 2025 20:25:54 +0000

🚀 Intro

The JavaScript module ecosystem is in transition. ESM (ECMAScript Modules) has become the modern standard, but CommonJS (CJS) remains deeply entrenched in the ecosystem.

ECMAScript Modules (ESM), introduced in ES6 (2015), is the standardised JavaScript module system designed to work seamlessly across both browsers and servers, unifying how JavaScript handles modularity.

Core advantages of ESM:

⚡ Enables better performance and optimisation through asynchronous loading and built-in tree-shaking via static analysis, allowing browsers and bundlers to eliminate unused code automatically.
🌐 Provides universal compatibility with native browser support (no bundlers required) while also working seamlessly on the server-side, making it suitable for both environments.
✨ Offers modern developer features, including top-level await support and dynamic imports in both module systems, giving developers more flexibility in how they structure and load their code.

As a library author, it’s important to support both legacy CommonJS projects and modern ESM projects. The solution is to publish a single npm package compatible with both module formats. This guide demonstrates how to build and publish a universal NPM package using the Nx Dev Toolkit and Rollup.

⚙️ Setting up Nx Workspace

Let’s start! Setting up an Nx workspace is the first step to building a supercharged, scalable project structure.

Create a publishable library (with rollup bundler)

bunx create-nx-workspace@22 dual-modules-workspace

cd dual-modules-workspace
bunx nx g @nx/js:lib packages/my-library --name my-library --importPath @dual-modules-workspace/my-library --bundler rollup --linter eslint --publishable --unitTestRunner vitest --setParserOptionsProject --useProjectJson

This creates:

...
packages
└── my-library
    ├── eslint.config.mjs
    ├── package.json
    ├── project.json
    ├── README.md
    ├── rollup.config.cjs
    ├── src/
    ├── tsconfig.json
    ├── tsconfig.lib.json
    ├── tsconfig.spec.json
    └── vite.config.ts
...

🔧 Setting up configurations

Now that the workspace is ready, it’s time to fine-tune the engine—let’s tweak the configs so everything runs smoothly and efficiently.

Rollup configuration

// packages/my-library/rollup.config.cjs

const { withNx } = require('@nx/rollup/with-nx');

module.exports = withNx(
  {
    main: './src/index.ts',
    outputPath: './dist',
    tsConfig: './tsconfig.lib.json',
    compiler: 'swc',
    format: ['esm', 'cjs'],
  },
  {
    output: {
      preserveModules: true, // Better tree-shaking
      preserveModulesRoot: '.', // Preserve module structure in output
    },
  }
);

Package configuration

// packages/my-library/package.json

{
  "name": "@dual-modules-workspace/my-library",
  "version": "0.0.1",
  "main": "./dist/index.cjs.js", // generated esm to cjs
  "module": "./dist/index.esm.js",
  "types": "./dist/index.d.ts", // generated index.esm.d.ts to index.d.ts
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "types": "./dist/index.d.ts", // generated index.esm.d.ts to index.d.ts
      "require": "./dist/index.cjs.js", // Support for common js
      "import": "./dist/index.esm.js",
      "default": "./dist/index.esm.js" // Keep ESM as default
    }
  },
  "sideEffects": false // // Better tree-shaking
  ...
}

The exports field in package.json routes import to ESM and require to CJS automatically.

Typescript declarations

Optionally, we can disable source maps added to the package by setting the property sourceMap to false in the tsconfig.

// tsconfig.base.json (not tsconfig.json)

{
  "compilerOptions": {
  ...
  "sourceMap": false,
  ...
  }
}

📦 Build

It’s showtime! Let’s run nx build and watch out library come to life after all that setup.

bun nx build my-library

This outputs:

packages/my-library/dist/
├── index.cjs.js
├── index.d.ts
├── index.esm.js
└── src
    ├── index.d.ts
    └── lib
        ├── my-library.cjs.js
        ├── my-library.d.ts
        └── my-library.esm.js

🚢 Publishing

Nx comes with a built-in command to seamlessly publish our packages to the npm registry. It also natively supports semantic versioning with conventional commits, making release management smooth and predictable. To get started, follow the step-by-step guide here, and explore additional release configuration options here to tailor the setup to our project’s needs.

🎉 Outro

Building universal npm packages with Nx and Rollup becomes straightforward once you grasp the key concepts. By setting up dual-format outputs, organising our package.json exports correctly, and validating our builds with the right tools, we ensure our library runs smoothly across the entire JavaScript ecosystem.

With our library now ready to serve both legacy and modern JavaScript consumers, you’ve crafted a package that’s versatile, robust, and future-proof.

If you found this guide helpful, don’t forget to leave a reaction or comment on this post — it helps me understand what content resonates with you and motivates me to create more like this!

Building Well-Architected AWS AppSync GraphQL APIs

sudokar — Mon, 14 Oct 2024 08:10:51 +0000

Intro

AWS AppSync is a fully managed serverless service from AWS for building scalable and resilient GraphQL APIs.

The AWS Well-Architected Framework and Serverless Application Lens offer best practices for building serverless applications in the cloud. This post will show how to apply these practices when creating GraphQL APIs with AWS AppSync, aligned with the Well-Architected pillars.

Operational Excellence

Focuses on running and monitoring systems to deliver business value, and continuously improving processes and procedures.

Enable Observability

Observability is the ability to understand the internal state of a system based on the data it generates, which includes logs, metrics, and traces. Together, these components enable you to monitor, troubleshoot, and optimise system behaviour efficiently.

AWS AppSync has built-in integration with AWS Cloudwatch for logs and metrics and X-Ray for tracing.

AppSync supports two types of logging: Request-level logging and Field-level logging. Field-level logging supports five logging levels (None, Error, Info, Debug and All), providing flexibility in the amount of detail captured for each GraphQL query.

AppSync captures a variety of default and enhanced metrics with detailed data points to monitor API performance and usage.

AppSync uses X-Ray to capture traces, allowing us to track the lifecycle of API requests, measure execution times for detailed performance analysis, and identify errors for easier troubleshooting.

When using Lambda resolvers, implement logging and manually instrument traces using AWS X-Ray SDK. Utilise libraries like Powertools for lambda and Middy

Use Infrastructure as Code (IaC)

For prototyping and deploying, consider using Infrastructure as Code (IaC) to enable tracking of changes using version control and releases. Cloudformation, Terraform, AWS SAM, and AWS CDK are a few examples.

If you are using AWS CDK, this CDK construct simplifies writing AppSync resolvers using Typescript.

Test, Test, Test

Testing is essential for building and releasing a bug-free system. From Day 0, create and implement a testing strategy for APIs built using AppSync.

Security

Ensures data protection, confidentiality, and integrity through identity management, security monitoring, and incident response.

Set up Authorisation

Unprotected APIs are easy targets for attackers seeking valuable data. AppSync offers built-in authorization support with API keys, IAM, OIDC, Cognito user pools, and Lambda authorizers.

Use Lambda authoriser for any custom/proprietary authorisation logic.

AppSync also has Cognito group-based authorisation that can be easily defined in GraphQL schema.

When using API keys, consider rotating them for better security and set up monitoring API key usage to identify any unusual activity, as they are less secure when compared to other types.

Use Private API

For applications running in AWS VPC or on-premises that need access to AppSync APIs, Create private APIs to reduce the attack surface.

Set up Web Application Firewall (WAF)

AWS WAF (Web Application Firewall) is a managed service that helps protect web applications from common threats and vulnerabilities

Configuring AWS Web Application Firewall (WAF) for AWS AppSync helps to enhance the security of your GraphQL APIs by providing multiple layers of protection.

Create roles with the least permissions

Roles created for resolvers should be set up with the most limited permissions to adhere to the principle of least privilege.

Keep secrets away from resolver code

You should not hard code API keys or secrets in resolver code; Instead, store it in Secrets Manager or Parameter Store and retrieve it.

With a pipeline resolver, the operation to fetch secrets can be executed before processing the external request. One downside would be it will impact the performance as the resolver needs to fetch a secret for each API request.

Disable Introspection

AppSync supports GraphQL introspection, a feature that allows clients to query the schema of a GraphQL API. It enables users to discover the types, fields, queries, mutations, and subscriptions available in the API, as well as the relationships between them.

Disable introspection for public users when applicable to enhance security and protect against vulnerabilities and data breaches.

Configure query depth limits

In AWS AppSync, query depth limit refers to a safeguard mechanism that restricts the maximum depth of nested queries allowed in a single GraphQL request. This limit helps prevent excessively deep or complex queries that could lead to performance issues or denial-of-service (DoS) attacks on your API.

Enforce reasonable limits on how deep queries can go, ensuring better overall stability and security of the application.

Reliability

Involves designing systems that recover from failures and dynamically meet demand.

Leverage Caching

AppSync supports both full request and per-resolver caching. Enable caching to reduce the load on backend systems.

Build reliable Lambdas

When using a Lambda resolver, implement retry logic to handle transient errors, allowing recovery and improving the function's reliability.

Allocate appropriate memory and set reasonable timeout limits based on the lambda's needs to prevent unnecessary failures.

As we all know, Everything fails all the time, implement error handling in Lambdas

Enable Pagination

AppSync uses token-based pagination; a token is used to specify the record after which additional items should be fetched, along with the page size.

Implement pagination to reduce the load on backend systems, improving API stability and reliability.

Performance Efficiency

Emphasises using computing resources efficiently to meet system requirements and maintain responsiveness.

Leverage Caching

Caching boosts the performance and reduces the latency of APIs built with AppSync.

Avoid Lambda resolver

AWS AppSync connects directly with data sources outside of Lambda. Using these connections directly reduces latency by eliminating one network hop, which enhances performance.

Optimise Lambda

When using Lambda resolvers, seek optimisations to enhance performance if Lambda is affecting overall latency.

Some optimisation techniques include reducing cold starts, keeping Lambda functions warm, enabling keep-alive for HTTP calls, configuring the required memory, using alternate runtimes like LLRT & Rust and using connection pooling.

Consider trade-offs when optimising Lambdas, as premature optimisations may not be necessary and could offer a low Return on Investment (ROI).

Utilise Subscriptions Effectively

AWS AppSync subscriptions are a feature that allows clients to receive real-time updates from a GraphQL API.

With AppSync subscriptions, ensure that the payload size is minimal and implement filtering on subscriptions to send only relevant data to clients.

Cost Optimisation

Helps control costs by using the right resources, eliminating waste, and scaling effectively.

Leverage Caching

Caching reduces the need to invoke resolvers for repeated requests, which in turn lowers the cost of Lambda invocations, DynamoDB queries, and other operations.

Setting up caching incurs initial costs since it relies on instances rather than being serverless. However, as AppSync serves more requests using the cache, it reduces overall costs.

Avoid Lambda resolver

As stated in the performance pillar above, Directly interacting with data sources reduces the cost of using Lambda.

Log what you need

Enabling verbose and full logging in AppSync can quickly increase your CloudWatch costs. Choose what to log carefully for troubleshooting.

Set a retention period for CloudWatch log groups, as application logs are usually needed for 2-4 weeks for troubleshooting. For longer storage, use AWS S3 with lifecycle policies to reduce costs.

AppSync does not support log sampling by default. Implement a custom sampling strategy to log detailed data every X minutes over Y hour(s).

Sustainability

Minimises environmental impact through efficient resource management and sustainable practices.

There are no sustainability practices to implement as the serverless paradigm continuously increases efficiency and reduces energy consumption as stated in the Serverless Architecture Lens

Outro

Building well-architected AWS AppSync GraphQL APIs requires a comprehensive approach that considers all aspects of the Serverless Architecture Lens. By following best practices and utilizing AWS AppSync's integration capabilities, you can create scalable, secure, and efficient GraphQL APIs for modern applications.

Remember, building a well-architected solution is an ongoing process. Regularly review your architecture against these pillars and make improvements as your application evolves.

Simplify AWS Appsync GraphQL API creation with strongly typed Typescript resolvers

sudokar — Sun, 30 Jul 2023 07:20:46 +0000

This post assumes familiarity with AWS Appsync and AWS CDK in general

Introduction

In this post, we'll look into creating an AWS Appsync GraphQL API with TypeScript using cdk-appsync-typescript-resolver AWS CDK construct. This powerful construct simplifies the creation of AWS AppSync resolvers in your CDK project, making it easier and more efficient for developers to work with AppSync.

Complete code is available in Github for reference

Codegen

We can generate Typescript types using GraphQL Code Gen easily.

These types are generated using Codegen CLI command graphql-codegen for this graphql schema using this codegen config file.

Note: Alternatively, We can use Amplify codegen as well

Resolver in Typescript

We can start writing our resolvers in Typescript using the Codegen generated types and the Appsync's utils package

Lets look at an example resolver. Link to File

import { Context, DynamoDBPutItemRequest, util } from "@aws-appsync/utils";
import { MutationAddTodoArgs, Todo } from "../types/appsync";

export function request(
  ctx: Context<MutationAddTodoArgs>
): DynamoDBPutItemRequest {
  const { id, ...attrValues } = ctx.args;

  return {
    operation: "PutItem",
    key: {
      id: util.dynamodb.toDynamoDB(id),
    },
    attributeValues: util.dynamodb.toMapValues({
      ...attrValues,
    }),
  };
}

export function response(
  ctx: Context<MutationAddTodoArgs, object, object, object, Todo>
) {
  return ctx.result;
}

This looks a lot better than writing resolvers in Javascript or VTL 😓

We can use types for context, various data sources supported by Appsync and built-in utilities along with generated types for GraphQL schema, which enhances the reliability and maintainability code through static type checking

Transpiling and Bundling

Unfortunately, we can't just sent the resolvers written in Typescript to Appsync yet. Like we transpile Typescirpt to Javascript for AWS Lambda, We will have to do the same for Appsync.

Unfortunately, as of today there is no built-in capability in CDK to do this for us. We will have to do it ourself using Esbuild or something similar, which transpiles and bundles code from Typescript to Javascript.

Using Esbuild's Javascript API, We have a custom CDK construct cdk-appsync-typescript-resolver that will automate the transpilation and bundling process for us.

An example of creating Typescript function using the custom construct AppsyncTypescriptFunction. This abstracts the transpiling and bundling process and setting default properties.

const addTodo = new AppsyncTypescriptFunction(this, "AddTodoFunction", {
      name: "addTodo",
      api: graphqlApi,
      dataSource: dynamoDataSource,
      path: path.join(__dirname, "addTodo.ts"),
      replaceStrings: {
          ENV: "prod",
      },
    });

JS resolvers doesn't support unit resolvers, supports only pipeline resolvers. When we want to create a unit resolver, we will have to use bit of boilerplate code and settings to make the pipeline resolver as unit resolver.

An added functionality to the construct is to define a property replaceStrings, which takes a map of from and to strings, used to replace strings in the transpiled and bundled code.

We have another CDK construct TSExpressPipelineResolver to use the AppsyncTypescriptFunction and sets up required boilerplate for us.

An example of using TSExpressPipelineResolver construct.

new TSExpressPipelineResolver(this, "AddTodoResolver", {
      api: graphqlApi,
      typeName: "Mutation",
      fieldName: "addTodo",
      tsFunction: addTodo,
    });

Note: We can use instance of AppsyncTypescriptFunction construct, which extends appsync.AppsyncFunction, in a regular appsync.Resolver construct too

Deploying the stack

You can find the complete code of this demo on GitHub.

cdk deploy

Tip

Catch invalid syntax (things not supported by Appsync's JS Resolver) while writing resolvers using the Eslint plugin @aws-appsync/eslint-plugin

Conclusion

By using the constructs from cdk-appsync-typescript-resolver, we can now take advantage of static typing and code editor's IntelliSense & inlay hints to make Appsync's resolvers easy and efficient. Generation of types from GraphQL schema makes it even more efficient. And also, With @aws-appsync/eslint-plugin we can get the benefit of finding invalid syntax while writing code.

Hope this was helpful!