Project Setup for Contribution

Relevant source files

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

• package.json
• tsconfig.json
• tsconfig.module.json
• vitest.config.js
• src/index.ts
• src/bundle.ts
• README.md

This document provides a technical overview of the consent-manager project's setup, covering dependencies, build processes, TypeScript configuration, and testing. It is intended for developers who wish to contribute to the project by providing a clear understanding of the development and build toolchain.

The project is a TypeScript-based library designed to be a flexible and comprehensive cookie consent management solution. The build system is configured to produce multiple distribution formats, including CommonJS, ES Modules, and a minified browser bundle, ensuring wide compatibility.

Dependencies

The project relies on several dependencies for its core functionality and development toolchain. These are managed in package.json.

Production Dependencies

These packages are required for the consent-manager to function in a production environment.

Package	Version	Description
deepmerge	^4.3.1	Used for recursively merging configuration objects.
is-plain-object	^5.0.0	Used to validate if a value is a plain JavaScript object, for cookie validation.
js-cookie	^3.0.5	A simple, lightweight library for handling browser cookies.

Sources: package.json:69-73

Development Dependencies

These packages are used for development tasks such as building, testing, and code quality.

Package	Version	Description
typescript	^5.1.6	The language used for the project's source code.
esbuild	^0.18.15	Used for bundling the project into JavaScript files for browser usage.
sass	^1.64.0	Used to compile SCSS files into CSS.
vitest	^0.33.0	The testing framework used for running unit tests.
jsdom	^22.1.0	Provides a DOM environment for tests running in Node.js.
npm-run-all	^4.1.5	Used to run multiple npm scripts in parallel or sequentially.
release-it	^16.1.3	A tool for automating versioning and package publishing.
@types/*	various	Type definitions for various libraries.

Sources: package.json:74-84

TypeScript Configuration

The project uses multiple tsconfig.json files to handle different build targets. The base configuration is in tsconfig.json, with tsconfig.module.json extending it for the ES module build.

Base Configuration (tsconfig.json)

This file configures the primary build for CommonJS modules.

• Target: es2017
• Module: commonjs
• Output Directory: dist/main
• Source Root: src
• Key Features: Generates declaration files (.d.ts), enables esModuleInterop, and includes dom libs.

Sources: tsconfig.json:1-55

The following diagram shows how the module-specific configuration extends the base configuration.

Sources: tsconfig.module.json:1-7, tsconfig.json

Key Compiler Options

Option	Value	Purpose
target	es2017	Compiles TypeScript down to ECMAScript 2017.
outDir	dist/main	Specifies the output directory for compiled files.
module	commonjs	Specifies the module code generation format.
declaration	true	Generates corresponding .d.ts files for type definitions.
esModuleInterop	true	Enables compatibility between CommonJS and ES Modules.
lib	["es2017", "dom"]	Includes type definitions for ES2017 and the DOM API.

Sources: tsconfig.json:3-10, tsconfig.json:49

Build and Development Scripts

The scripts section in package.json defines the tasks for building, developing, and testing the project.

Build Process

The main build script orchestrates several sub-tasks in parallel to create the complete distribution package.

Sources: package.json:41-51

Script Descriptions

Script	Command	Description
prebuild	rm -rf dist/	Cleans the dist directory before a new build.
build	run-p build:*	Runs all build:* scripts in parallel.
build:main	tsc -p tsconfig.json	Compiles TypeScript to CommonJS modules.
build:module	tsc -p tsconfig.module.json	Compiles TypeScript to ESNext modules.
build:bundle	esbuild src/bundle.ts --bundle ...	Creates a non-minified browser bundle.
build:bundle-min	esbuild src/index.ts --bundle --minify ...	Creates a minified browser bundle for CDN usage (unpkg).
build:styles	sass src/styles.scss ...	Compiles SCSS to a non-minified CSS file.
build:styles-min	sass src/styles.scss ... --style compressed	Compiles SCSS to a minified CSS file.
dev	rm -rf dist/ && run-p dev:*	Starts all development watch tasks in parallel.
test	vitest run	Executes the test suite.

Sources: package.json:41-66

Entry Points

The project has two primary TypeScript entry points for its different bundles:

1. src/index.ts: This is the main entry point for the ES Module and CommonJS builds. It exports the core ConsentManager class and named exports for DOMConnector and GrantsInterface. This file is also used for the minified browser bundle (consent-manager.min.js).
   Sources: src/index.ts:1-5, package.json:46
2. src/bundle.ts: This entry point is specifically for the non-minified, unpkg-style browser bundle (consent-manager.js). It imports all major classes and attaches them to the global window object, making them immediately available in a browser environment when the script is included via a <script> tag.
   Sources: src/bundle.ts:1-8, package.json:45

// src/bundle.ts
import ConsentManager from './modules/ConsentManager';
window.ConsentManager = ConsentManager;

import DOMConnector from './modules/DOMConnector';
window.DOMConnector = DOMConnector;

import GrantsInterface from './modules/GrantsInterface';
window.GrantsInterface = GrantsInterface;

This snippet from src/bundle.ts shows how the classes are exposed on the window object for direct browser usage.
Sources: src/bundle.ts:1-8

Testing

The project uses Vitest for unit testing, configured to run in a jsdom environment. This allows tests to interact with a simulated browser DOM, which is crucial for testing UI-related components like GrantsInterface and DOMConnector.

The configuration is defined in vitest.config.js.

// vitest.config.js
/// <reference types="vitest" />
import { defineConfig } from 'vite'

export default defineConfig({
  test: {
    environment: 'jsdom'
  },
})

Sources: vitest.config.js:1-8

Tests are executed by running the npm test command, which invokes vitest run.

Sources: package.json:65

Summary

Contributing to consent-manager requires familiarity with TypeScript, npm scripts, and the tools used in the build process (tsc, esbuild, sass). The project is structured to produce multiple, distinct artifacts for different use cases from a single TypeScript codebase. The development workflow is streamlined with parallel watch scripts, and testing is handled by Vitest in a simulated DOM environment. This robust setup ensures code quality and broad compatibility for the distributed package.