TICKETING-CONFIG

Overview

This project is a utility package that provides shared configuration files for ticketing TypeScript projects. The main goal of this package is to centralize and standardize tooling configuration (ESLint, Prettier, etc.) across all projects in the ticketing ecosystem.

Note: This is a private scoped package. Ensure your local environment is properly configured and you have the necessary permissions to work with the package. Logging into the correct NPM account or an NPM token is required for installation or publishing.

Requirements

To ensure compatibility, make sure your project meets the following minimum version requirements:

• Node.js: >= 14.0.0
• pnpm: >= 8.0.0 (Mandatory package manager)
• ESLint: >= 9.0.0 (required; this package uses flat config only)
• TypeScript: >= 4.5.0
• Prettier: >= 3.0.0
• Angular (optional): >= 17.0.0 (if using Angular-specific linting)

Installation

Using pnpm

This project strictly uses pnpm. If you are using npm or yarn, we recommend switching to pnpm to ensure consistent dependency resolution.

1. Install pnpm globally if you haven't already:

   pnpm add -g pnpm

2. Install the package in your project:

   pnpm add -D @3ddv/ticketing-config

Installing Peer Dependencies

This package has several peer dependencies. You only need to install the ones related to the configuration you are using. All ESLint-related peers are optional; install those required by the shared config you consume.

ESLint (flat config) — requires ESLint 9+. Use with eslint.config.js / eslint.config.mjs:

pnpm add -D \
  @eslint/js \
  @smarttools/eslint-plugin-rxjs \
  angular-eslint \
  eslint@^9 \
  eslint-config-prettier \
  eslint-plugin-boundaries \
  eslint-plugin-prettier \
  eslint-plugin-unicorn \
  typescript-eslint

If you use Prettier:

pnpm add -D prettier

NOTE: The package is structured with multiple entry points, so if you don't use Prettier, you don't need to install it.

How to Use It

Using ESLint Configuration (flat config)

The package exports an ESLint flat config (ESLint 9+). Create an eslint.config.js (or eslint.config.mjs for ESM) in your project root:

import config from '@3ddv/ticketing-config/eslint';

export default config;

CommonJS (eslint.config.cjs):

const config = require('@3ddv/ticketing-config/eslint');

module.exports = config;

Extending the Configuration

You can extend or override the shared config by spreading it and adding or overriding entries:

import baseConfig from '@3ddv/ticketing-config/eslint';

export default [
  ...baseConfig,
  {
    files: ['**/*.spec.ts'],
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
    },
  },
];

Zero-Config Usage (Root-less)

If you want to keep your project root clean, you can configure your tools directly in package.json. This avoids having a .prettierrc file in your root directory.

Why isn’t ESLint config in package.json supported?
ESLint 9 uses the flat config format and looks for eslint.config.js (or .mjs/.cjs) by design. The legacy eslintConfig key in package.json was only for the old eslintrc format; the ESLint team did not add flat config support there, so you must use an eslint.config.js (or similar) file. Prettier can still be pointed at this package from package.json.

Prettier in package.json

{
  "prettier": "@3ddv/ticketing-config/prettier"
}

Local Development Consumption

During development, you can link the package locally in your package.json:

{
  "devDependencies": {
    "@3ddv/ticketing-config": "file:../../libs/ticketing-config"
  },
  "prettier": "./node_modules/@3ddv/ticketing-config/build/prettier.js"
}

Use the shared ESLint config via eslint.config.js:

import config from '@3ddv/ticketing-config/eslint';

export default config;

Note: When using the file: prefix for local consumption, Prettier can point to ./node_modules/@3ddv/ticketing-config/build/prettier.js so the tool resolves correctly from the symlinked location.

Collaborate

To collaborate on this project, follow these steps:

1. Install dependencies:

   pnpm install

2. Create your new feature branch: Make sure main and feature/ticketing-config are up to date in your local copy (git pull). Create your new feature branch from feature/ticketing-config.

3. Making changes: Add or modify the code as needed. Ensure your changes are thoroughly documented.

4. Merge to the main feature branch: After making changes, merge your changes to feature/ticketing-config via pull request. This will ensure that the generated tags are linked to the correct branch when releasing a new version.

5. Checkout to the feature/ticketing-config branch and make sure it is up to date by pulling the latest changes from the remote repository.

6. Versioning and releasing changes: Use pnpm run release-* to bump the npm version. This step will automatically update the version number based on the changes made.

   pnpm run release-patch

   pnpm run release-minor

   pnpm run release-major

7. Publishing the changes: Run pnpm run publish-version. This command will rebuild the project, associate the publishing version with the commit tag, and then execute npm publish to upload the changes to the npm package repository. This will also add the corresponding workspace commits to CHANGELOG.md.

   pnpm run publish-version

8. Commit all changes and create a pull request from feature/ticketing-config to main: Keep main and feature/ticketing-config always in sync.

9. Updating Local Project Dependency: After publishing, remember to update the package in your local project:

   pnpm install @3ddv/ticketing-config@latest

Conventions

Semantic Versioning

This project follows semantic versioning. We release patch versions for critical bugfixes, minor versions for new features or non-essential changes, and major versions for any breaking changes.

Refer to the official manifesto for any further information.

Conventional Commits

For managing our commit history and versioning, we follow the Conventional Commits specification. This structured format for commit messages enables us to handle our release process, making it clear when a commit introduces new features, fixes bugs, or includes breaking changes.

Refer to the official documentation for any further information.

How to Add New Configurations

To add a new configuration file to this package, follow these steps:

1. Create the Configuration File: Create a new TypeScript file in src/configs/ containing your configuration object.

   // src/configs/my-config.config.ts
   const myConfig = {
     // detailed configuration
   };
      
   export default myConfig;

2. Create the Entry Point: Create a new file in src/ to export your configuration. This file will be the entry point for utilizing the config.

   // src/my-config.ts
   import myConfig from './configs/my-config.config';
      
   export = myConfig;

3. Export in Index: Export the configuration object in src/index.ts to make it available via the main package import.

   // src/index.ts
   export { default as myConfig } from "./configs/my-config.config";

4. Update Build Script: Add a new build step in scripts/esbuild.js to compile your new entry point.

   // scripts/esbuild.js
   build({ ...shared, entryPoints: ['./src/my-config.ts'], outfile: 'build/my-config.js', format: 'cjs' }).catch(() => process.exit(1));
   build({ ...shared, entryPoints: ['./src/my-config.ts'], outfile: 'build/my-config.esm.js', format: 'esm' }).catch(() => process.exit(1));

5. Build: Run pnpm build to generate the new configuration file in the build/ directory.

6. Usage: You can now use your new configuration in other projects:

   // .myconfigrc.js
   module.exports = require('@3ddv/ticketing-config/my-config');