NPM-Template

Documentation

Welcome to The-Node-Forge npm-template! This repository serves as a template for The Node Forge members to quickly scaffold a new TypeScript-based NPM package with built-in linting, testing, documentation, and CI/CD.

---

✨ Getting Started

To use this template, follow these steps:

1. Clone this repository or create a new one from this template.
2. Update necessary details in package.json:
   • "name" → Change to your package name.
   • "version" → Set your initial version (1.0.0).
   • "author" → Add your name.
   • "repository" → Update the GitHub URL (if not autogenerated).
3. Install dependencies:

   npm install

4. Start development:

   npm run build

---

📜 Available Scripts

The package.json includes several useful scripts:

Script	Description
npm run test	Runs Jest tests.
npm run test:watch	Runs Jest in watch mode.
npm run test:coverage	Runs Jest with coverage report.
npm run format	Formats the code using Prettier.
npm run format:check	Checks if code follows Prettier formatting.
npm run lint	Runs ESLint to check for issues.
npm run lint:fix	Automatically fixes lint issues.
npm run build	Compiles TypeScript code to JavaScript.
npm run docs:build	Builds documentation using Docusaurus.
npm run docs:start	Runs Docusaurus locally for preview.
npm run docs:clean	Cleans and rebuilds documentation.
npm run docs:deploy	Deploys docs to GitHub Pages.

---

📘 Documentation with Docusaurus

This repository uses Docusaurus to generate project documentation. Documentation lives in the docs/docs/ folder.

✏️ Customizing Documentation

1️⃣ Enable github pages for your repo

• Start by going to this repo in github vselect settings > pages > (build and development) > deploy from branch > gh-pages > /(root)

2️⃣ Where to Edit Documentation

📂 docs/docusaurus.config.ts

• remove any instance of /npm-template/ and add your /repo-name/
• Edit baseUrl to match repo name /repo-name/.
• Edit meta data to matcg your package details, comments left to help

📂 docs/docs/

• Houses main documentation files.

📂 docs/docs/api/

• Autogenerated API documentation from JSDoc comments. (optional)

📂 docs/docs/

• 6 Guides written in Markdown, all need to be filled out.
• API_REFERENCE, CHANGELOG, CODE_OF_CONDUCT, INSTALLATION, USAGE, intro.md (use readme.md info)

📂 docs/static/PROJECTMARKDOWN.md

• Add your project readme here, this is your documentation landing page

📂 docs/src/components/HomepageFeatures/index.tsx

• Edit Documentation Splashpage.

---

🛠️ Auto-Generating API Documentation

This repository uses JSDoc to document code and generate API references automatically.

🔍 How Auto Documentation Works

• 📂 docs/docs/api/ → Contains autogenerated documentation.
• JSDoc comments inside TypeScript files provide function and class documentation.
• Docusaurus and TypeDoc process these comments into readable documentation.

✅ Example JSDoc Comment

/**
 * Generates a unique package identifier based on package name and version.
 *
 * @param {string} packageName - The name of the NPM package.
 * @param {string} version - The package version (must follow SemVer: MAJOR.MINOR.PATCH).
 * @returns {string} A unique identifier in the format "packageName@version".
 * @throws {Error} Throws an error if the version is not in SemVer format.
 *
 * @example
 * const packageId = generatePackageIdentifier("my-awesome-package", "1.2.3");
 * console.log(packageId); // "my-awesome-package@1.2.3"
 */

export function generatePackageIdentifier(
  packageName: string,
  version: string,
): string {
  const semverRegex = /^\d+\.\d+\.\d+$/;

  if (!semverRegex.test(version)) {
    throw new Error(
      'Invalid version format. Must follow Semantic Versioning: MAJOR.MINOR.PATCH',
    );
  }

  return `${packageName}@${version}`;
}

🔄 Generating API Documentation

To generate API documentation based on JSDoc comments, run:

npm run docs:build

This will create or update documentation inside docs/docs/api/.

To preview the changes, run:

npm run docs:start

3️⃣ Building & Running Documentation

After you edit or majke any documentation changes you want to clean, and rebuild your docs

To generate and preview documentation:

npm run docs:clean   # rm -rf docs/build and runs build
npm run docs:start   # Run the docs locally

• Open http://localhost:3000/ to view the site.

To deploy to GitHub Pages:

Your Docusaurus docs will build to github pages on push to main. Make sure all docs are filled out for a properly scaffolded documention gh-page

---

🛠️ Code Quality & Formatting

This template includes ESLint and Prettier to enforce code quality.

🛠️ ESLint Configuration

• Enforces best practices and TypeScript rules.
• Ignores everything in /docs/ (Docusaurus files).
• Auto-fixes issues using:

  npm run lint:fix

🔧 Prettier Configuration

• Formats the code automatically.
• Enforces consistent spacing, semicolons, and line breaks.

To apply formatting:

npm run format

---

⚖️ Continuous Integration (CI)

🔄 What CI Does

• Runs tests automatically on every push or pull request.
• Formats & lints code, fixing issues before merging.
• Prevents PRs without tests.
• Uploads test coverage results.

⚙️ How CI Works (.github/workflows/ci.yaml)

Step	Purpose
✅ Install Dependencies	Installs required NPM packages.
✅ Run Prettier	Auto-formats code.
✅ Run ESLint	Fixes linting issues.
✅ Check for Tests	Ensures PRs include test files.
✅ Run Jest Tests	Executes all unit tests.
✅ Upload Coverage	Stores Jest test results.
✅ Commit Auto-Fixes	Commits any auto-fixes to the branch.

If you push broken code, CI fails and prevents merging. 🚨

---

🌟 Final Checklist for New Repos

✔ Update package.json
✔ Modify documentation in docs/
✔ Run tests before committing (npm run test)
✔ Ensure CI passes before merging

---

💡 Need Help?

If you run into any issues, reach out to The Node Forge team on GitHub!

Happy coding! 🚀