Coding Conventions

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• README.md
• src/bundle.ts
• src/index.ts
• src/modules/ConsentManager.test.ts
• src/modules/ConsentManager.ts
• src/modules/DOMConnector.ts
• src/modules/GrantsInterface.ts
• src/styles.scss
• tsconfig.json
• tsconfig.module.json
• vitest.config.js

This document outlines the coding conventions, project structure, and build processes for the consent-manager project. The conventions are derived from the project's configuration files and source code, ensuring consistency and maintainability. The project is built with TypeScript and SASS, and it targets multiple module formats for broad compatibility.

The core logic is written in TypeScript, with a clear separation of concerns into modules like ConsentManager, DOMConnector, and GrantsInterface. Styling is handled by SASS using a consistent naming scheme. The build system uses tsc, esbuild, and sass to compile the source code into distributable formats. Testing is performed using Vitest in a JSDOM environment.

TypeScript Configuration

The project uses TypeScript with a base configuration file, tsconfig.json, which is extended by tsconfig.module.json for a specific build target. This allows for different module outputs while sharing common compiler settings.

Sources: tsconfig.json, tsconfig.module.json

Compiler Targets and Modules

The project compiles to multiple JavaScript module formats to support various consumption methods.

• CommonJS: The primary build target, configured in tsconfig.json, compiles to commonjs modules targeting es2017. This is intended for Node.js environments.
• ESNext Modules: The tsconfig.module.json extends the base configuration to output esnext modules, also targeting esnext. This is for modern bundlers that support tree-shaking.
• Browser Bundle: esbuild is used to create a browser-compatible bundle, which exposes the modules on the window object.

Sources: tsconfig.json:3-7, tsconfig.module.json:3-6, package.json:28-31, src/bundle.ts

This diagram shows the inheritance of TypeScript configurations.

Key Compiler Options

The following table summarizes important compiler options that enforce code quality and style. Strict type-checking options like strict are commented out, indicating a more lenient but still type-safe approach.

Option	Value	Description
target	es2017	The base ECMAScript target version.
module	commonjs	The base module system.
declaration	true	Generates corresponding .d.ts files.
esModuleInterop	true	Enables interoperability between CommonJS and ES Modules.
noUnusedLocals	true	Reports errors on unused local variables.
noUnusedParameters	true	Reports errors on unused function parameters.
noImplicitReturns	true	Reports errors when not all code paths in a function return a value.
lib	["es2017", "dom"]	Includes type definitions for ES2017 and the DOM API.

Sources: tsconfig.json:3-40

Project Structure

The project follows a standard structure for a TypeScript library, separating source code, tests, and distribution files.

This diagram illustrates the main directories and key files within the project.

Sources: package.json:8-13, tsconfig.json:43-44, src/index.ts, src/bundle.ts, src/modules/ConsentManager.ts

Build Process

The build process is managed by npm scripts defined in package.json. It uses tsc for TypeScript compilation, esbuild for bundling, and sass for stylesheet compilation.

Sources: package.json:26-41

Build Scripts

Script	Command	Description
build:main	tsc -p tsconfig.json	Compiles TypeScript to CommonJS modules in dist/main.
build:module	tsc -p tsconfig.module.json	Compiles TypeScript to ESNext modules in dist/module.
build:bundle	esbuild src/bundle.ts ...	Creates a non-minified browser bundle at dist/consent-manager.js.
build:bundle-min	esbuild src/index.ts ...	Creates a minified browser bundle at dist/consent-manager.min.js.
build:styles	sass src/styles.scss ...	Compiles SASS to CSS at dist/consent-manager.css.
build:styles-min	sass src/styles.scss ...	Compiles and minifies SASS to dist/consent-manager.min.css.

The following diagram shows the flow from source files to distributable artifacts.

Styling Conventions

The project uses SASS (.scss) for styling the UI components provided by GrantsInterface. The class naming follows a BEM-like (Block, Element, Modifier) convention, using the block name consent-manager.

Naming Convention Examples

Selector	Description
.consent-manager--banner-wrapper	The main block/container for the consent banner.
.consent-manager--banner-info	An "info" element within the banner block.
.consent-manager--modal-container	The main block for the modal.
.consent-manager--modal-title	A "title" element within the modal block.

This consistent naming scheme prevents style conflicts and makes the CSS structure predictable.

Sources: src/styles.scss, src/modules/GrantsInterface.ts:70, 240

Testing Conventions

Testing is set up using Vitest with the JSDOM environment, allowing for DOM testing in a Node.js context.

• Framework: Vitest is configured in vitest.config.js.
• Test Runner: The test script in package.json runs vitest run.
• Test Files: Test files use the .test.ts suffix, such as ConsentManager.test.ts.
• Structure: Tests are organized using describe blocks for grouping related tests, and individual test cases are defined with test(). Assertions are made using expect. Mocks are created using vi.fn().

// Example from src/modules/ConsentManager.test.ts
import { expect, describe, beforeEach, vi, test } from 'vitest';
import Cookie from 'js-cookie';

import ConsentManager from './ConsentManager';

describe('ConsentManager', () => {
  beforeEach(() => {
    Cookie.remove('consent-manager');
  });

  test('constructor - default config', () => {
    const consentManager = new ConsentManager({
      version: '1',
      categories: [],
    });

    expect(consentManager.config.cookieName).toBe('consent-manager');
  });
});

Sources: vitest.config.js, package.json:42, src/modules/ConsentManager.test.ts

Module and Entry Points

The project is structured to be consumed in multiple ways, defined by the entry points in package.json and the source entry files.

• main: dist/main/index.js (CommonJS)
• module: dist/module/index.js (ES Module)
• unpkg: dist/consent-manager.min.js (Browser/CDN bundle)

The source file src/index.ts serves as the primary entry point for module exports, while src/bundle.ts is used specifically to create the browser bundle that attaches modules to the window object.

Sources: package.json:5-8, src/index.ts, src/bundle.ts