Currently I have finished working on the Lambda function, and I am working towards the deployment of the API Gateway HTTP API and DynamoDB table. This post is a walkthrough of the source code, testing, and build process, that I and AI pair-programmed together. The source code is available on GitHub.

What Was Built​

1. Source Architecture​

• src/types.ts: Strongly typed models for CounterRecord, CounterResponse, ErrorResponse, and AppConfig.
• src/config.ts: Environment variable loader for TABLE_NAME, ALLOW_ORIGIN, DEFAULT_PAGE_ID, and AWS_REGION.
• src/utils.ts: CORS headers, API Gateway v2 response builders, and pageId sanitization (validates characters and restricts max length to 128 characters).
• src/counter.ts: DynamoDB atomic operations using AWS SDK v3 DynamoDBDocumentClient:
  • incrementCounter: Uses atomic update expression:

    SET #count = if_not_exists(#count, :zero) + :inc, #updatedAt = :now
    

  • getCounter: Reads count without incrementing; returns { count: 0, updatedAt: null } for unvisited pages.
• src/handler.ts: Main AWS Lambda handler (APIGatewayProxyHandlerV2):
  • Handles OPTIONS CORS preflight requests (HTTP 204).
  • Routes POST to increment counter.
  • Routes GET to read counter.
  • Returns HTTP 405 for unsupported HTTP methods.
  • Returns HTTP 400 for malformed input or invalid pageId.
  • Returns HTTP 500 for missing config or database errors.

2. Testing & Tooling​

• package.json: Configured with @aws-sdk/client-dynamodb, @aws-sdk/lib-dynamodb, esbuild, jest, ts-jest, and aws-sdk-client-mock.
• jest.config.js: Unit test configuration with ts-jest and coverage thresholds.
• tests/counter.test.ts: Unit tests for DynamoDB atomic increments and reads.
• tests/handler.test.ts: End-to-end event routing, CORS, query/body parsing, and error handling.
• tests/config.test.ts: Environment variable validation tests.
• tests/utils.test.ts: Sanitization, validation, and CORS tests.
• README.md: Documentation including DynamoDB table creation, IAM permissions, API Gateway HTTP API setup, and frontend client snippet.

Validation Results​

1. TypeScript Strict Typecheck​

npm run typecheck

Passed with 0 errors.

2. Jest Test Suite with Coverage​

npm run test:coverage

PASS tests/config.test.ts
PASS tests/utils.test.ts
PASS tests/counter.test.ts
PASS tests/handler.test.ts

------------|---------|----------|---------|---------|-------------------
File        | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
------------|---------|----------|---------|---------|-------------------
All files   |    96.8 |    90.69 |   85.71 |    96.8 |
 config.ts  |     100 |    88.88 |     100 |     100 |
 counter.ts |     100 |       80 |     100 |     100 |
 handler.ts |    93.1 |      100 |      50 |    93.1 |
 utils.ts   |   97.29 |    94.11 |     100 |   97.29 |
------------|---------|----------|---------|---------|-------------------

Test Suites: 4 passed, 4 total
Tests:       33 passed, 33 total

3. Build & Package Verification​

npm run package

• Bundled via esbuild to CommonJS Node.js 20 target.
• Produced dist/visitor-counter.zip (577 KB), verified dist/index.js exports handler.

Two of the most powerful tools in the JavaScript ecosystem for managing Git hooks and code quality are Husky and Lint-Staged.

In this post, we'll explore what these tools are, why they are important, how to set them up, and how to test your configuration locally.

What are Husky and Lint-Staged?​

Husky​

Husky is a tool that allows you to easily tie scripts to Git hooks. Git hooks are scripts that Git executes before or after events such as: commit, push, and receive. Husky makes it simple to manage these hooks within your package.json or as separate script files, ensuring they are automatically installed for everyone who works on the project.

Lint-Staged​

Lint-Staged is a tool that allows you to run linters (like ESLint, Prettier, or cspell) against staged git files and don't let it slip into your codebase. Running linters on the entire project can be slow. Lint-Staged solves this by only running checks on files that are actively being modified and staged for a commit.

Why is it Important?​

1. Catches Errors Early: By running linting, formatting, and spell checks on every commit, you catch simple mistakes before they even leave your local machine or trigger a CI build.
2. Enforces Consistency: It ensures that all code pushed to the repository adheres to the team's defined standards (e.g., Prettier formatting, ESLint rules).
3. Improves Code Reviews: When the code is consistently formatted, code reviews can focus on the actual logic and architecture rather than nitpicking spacing or syntax issues.
4. Saves CI Time: Failing fast locally means your continuous integration (CI) pipeline doesn't have to waste time running jobs that fail on trivial style errors.

How to Set It Up​

Let's walk through setting up Husky and Lint-Staged to run ESLint, Prettier, and a spell checker (cspell) on pre-commit.

1. Install Dependencies​

First, ensure you have Husky, Lint-Staged, and your desired linters installed as devDependencies:

npm install --save-dev husky lint-staged eslint prettier cspell

2. Initialize Husky​

Run the Husky initialization script. This sets up the .husky directory and prepares Git to use it:

npx husky init

This command typically adds a prepare script in your package.json to ensure Husky is installed automatically after npm install.

{
  "scripts": {
    "prepare": "husky"
  }
}

3. Create a Pre-commit Hook​

Next, we need to instruct Husky to run lint-staged before every commit.

If npx husky init created a default pre-commit hook (usually echoing something or running npm test), you can overwrite it. Run the following command or edit the .husky/pre-commit file directly:

echo "npx lint-staged" > .husky/pre-commit

4. Configure Lint-Staged​

Finally, configure lint-staged in your package.json to define which tools run on which files. Here is an example configuration:

{
  "lint-staged": {
    "**/*.{md,mdx}": "cspell lint",
    "**/*.{js,jsx,ts,tsx,json,md,mdx,css}": "prettier --write",
    "src/**/*.{js,jsx,ts,tsx}": "eslint"
  }
}

Explanation of the config:

• **/*.{md,mdx}: Runs the spell checker (cspell) on all Markdown and MDX files.
• **/*.{js,jsx,ts,tsx,json,md,mdx,css}: Runs Prettier to automatically format code. The --write flag tells Prettier to save the formatted changes back to the files.
• src/**/*.{js,jsx,ts,tsx}: Runs ESLint on your source code to catch potential logic errors or rule violations.

How to Test It Locally​

Once configured, testing the setup is straightforward.

1. Make a Change: Modify a file that matches your lint-staged configuration. For example, add some unformatted code to a JavaScript file or a typo to a Markdown file.
2. Stage the File:

   git add path/to/your/file.js
   

3. Attempt a Commit:

   git commit -m "Test husky setup"
   

What should happen?

• Husky intercepts the commit process.
• It executes npx lint-staged.
• Lint-Staged looks at the staged file (file.js).
• It runs the configured tools (e.g., prettier --write and eslint).
• If everything passes: The formatted file is added to the commit, and the commit succeeds.
• If a linter fails (e.g., ESLint finds an error): The commit is aborted, and the error output is displayed in your terminal, forcing you to fix the issue before committing again.

By setting up Husky and Lint-Staged, you automate quality control directly within the developer workflow, leading to cleaner codebases and more efficient teams. Happy coding!

• ESLint is a powerful static code analysis tool that finds and fixes problems in your JavaScript or TypeScript code. It ensures that your code adheres to specific stylistic guidelines and catches potential runtime errors before the code is even executed.
• Prettier is an opinionated code formatter. Its sole job is to take your code and re-format it to ensure visual consistency across the entire project. It ends debates over spaces versus tabs, trailing commas, and line length.
• CodeQL is a semantic code analysis engine developed by GitHub. It allows you to query your code as if it were a database to find security vulnerabilities and bugs. It is highly popular because it integrates seamlessly into the GitHub ecosystem.

Installing packages​

To get started, we need to install the necessary packages for ESLint and Prettier. We don't need to install CodeQL locally as it is provided as a free service via GitHub Actions and runs directly in the CI/CD pipeline.

Run the following command in your terminal to install the necessary development dependencies:

npm install -D eslint prettier eslint-config-prettier eslint-plugin-prettier eslint-plugin-react eslint-plugin-react-hooks @typescript-eslint/parser @typescript-eslint/eslint-plugin

Next, you will need to create the configuration files for these tools in the root directory of your project.

ESLint Configuration (.eslintrc.js)​

Create a .eslintrc.js file and add the following configuration to integrate ESLint with React, TypeScript, and Prettier:

module.exports = {
  env: {
    browser: true,
    es2021: true,
    node: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:react/recommended',
    'plugin:react-hooks/recommended',
    'plugin:prettier/recommended',
  ],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaFeatures: {
      jsx: true,
    },
    ecmaVersion: 12,
    sourceType: 'module',
  },
  plugins: ['react', '@typescript-eslint', 'prettier'],
  rules: {
    'prettier/prettier': 'warn',
    'react/react-in-jsx-scope': 'off',
    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
  },
  settings: {
    react: {
      version: 'detect',
    },
  },
};

Prettier Configuration (.prettierrc)​

Create a .prettierrc file to define your code formatting rules:

{
  "semi": true,
  "trailingComma": "all",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2
}

Configure package.json​

To easily execute ESLint and Prettier, we need to add several scripts to our package.json file.

Update the "scripts" block in your package.json to include the following lines:

{
  "scripts": {
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "lint": "eslint \"src/**/*.{js,jsx,ts,tsx}\""
  }
}

• "format": Runs Prettier across the entire project directory and overwrites the files with the properly formatted code.
• "format:check": Runs Prettier in check mode, outputting any files that are not formatted correctly without modifying them. This is particularly useful for CI environments.
• "lint": Runs ESLint targeting all JavaScript and TypeScript files within the src/ directory to catch errors and enforce code quality.

Ignore files​

We don't want our linting and formatting tools to scan compiled output, third-party libraries, or cache folders. To prevent this, we must create two ignore files: .eslintignore and .prettierignore.

Create both .eslintignore and .prettierignore in the root of your project and add the following folders to them:

node_modules
build
dist
.docusaurus
coverage

• node_modules: Contains third-party dependencies which we should not lint or format.
• build & dist: Compiled production outputs.
• .docusaurus: Docusaurus cache and auto-generated build files.
• coverage: Test coverage reporting output directory.

Testing​

Now the most important part: ensuring our setup works locally.

To test that Prettier is correctly formatting files, run the following command in your terminal:

npm run format

Expected Output: Prettier will scan through your project and automatically reformat any file that does not meet the standards defined in .prettierrc. The terminal will list the files it has processed.

To check for any potential code quality issues using ESLint, run:

npm run lint

Expected Output: ESLint will scan the files in the src/ directory. If your code is completely valid and follows all rules, the command will silently exit without any output. If there are code errors or stylistic violations, it will print a detailed report indicating the exact file, line number, and error/warning message.

GitHub Actions CI Integration​

To ensure no code regressions are introduced into the main branch, these tools are executed automatically in our CI pipeline.

In our .github/workflows/ci.yml file, we added steps to invoke both our formatting check (npm run format:check) and our linting script (npm run lint). If any of these scripts fail, the CI run will fail, blocking the pull request from being merged.

Additionally, a separate .github/workflows/codeql-analysis.yml workflow was introduced. This workflow initializes the CodeQL environment, builds the project (if necessary), and analyzes the codebase for common vulnerabilities, reporting them directly in the GitHub Security tab of the repository.

Docusaurus Blog Features Summary​

This blog is powered by Docusaurus, which provides several great features out-of-the-box:

• MDX Support: Blog posts support Docusaurus Markdown features, such as MDX. This allows the use of React components (like interactive buttons) and Admonitions (callouts/tips) directly inside the markdown files.
• Truncation: The {/* truncate */} comment can be used to limit the blog post size in the list view, keeping the main blog page clean and readable.
• File Organization: Posts can be standalone markdown files or placed within their own folders, which is convenient for co-locating images specific to a post.
• Metadata: The blog post date can be automatically extracted from filenames (e.g., 2026-09-17-welcome.mdx), and author/tag metadata is easily managed via authors.yml and tags.yml.