Package Exports

@twin.techies/gst-invoice

Readme

@twin.techies/gst-invoice

Generate GST-compliant invoices for India — automatic CGST/SGST vs IGST tax calculation, PDF rendering with 5 templates, and e-invoice (NIC schema v1.1) JSON export.

🚀 Try it live (no install)

👉 Interactive playground on Storybook — build invoices, validate GSTINs, see tax math live, browse 5 templates.

Stories available:

GSTIN Validator — real checksum validation
Tax Computation — live CGST/SGST vs IGST split
Invoice Builder — full form → HTML preview
Template Gallery — visual mocks of all 5 PDF templates
E-Invoice JSON — NIC IRP v1.1 schema export

The Storybook is a browser preview — PDF download is disabled there because PDF generation requires Node.js. The full library generates real PDFs in your own Next.js / Node app — copy the example code from any story.

Or open a RunKit notebook → and paste this to see the tax math instantly:

const { computeInvoice, toEInvoiceJSON, amountInWordsINR } = require('@twin.techies/gst-invoice');

const invoice = computeInvoice({
  meta: { invoiceNumber: 'INV-001', invoiceDate: '2026-05-23' },
  seller: {
    name: 'My Company', gstin: '27AAPFU0939F1ZV', stateCode: '27',
    address: { line1: 'Pune Office', city: 'Pune', state: 'Maharashtra', pincode: '411057' },
  },
  buyer: {
    name: 'Client Co', gstin: '29AAACB1234A1ZF', stateCode: '29',
    address: { line1: 'BLR Office', city: 'Bengaluru', state: 'Karnataka', pincode: '560001' },
  },
  items: [
    { description: 'Software License', hsn: '998313', quantity: 10, rate: 5000, gstRate: 18 },
  ],
});

invoice.totals;        // { taxableValue: 50000, igst: 9000, grandTotal: 59000, ... }
invoice.isInterState;  // true → IGST applied (different states)
amountInWordsINR(invoice.totals.grandTotal);  // "Fifty Nine Thousand Rupees Only"

For PDF generation, open a full StackBlitz Node sandbox → (WebContainer supports filesystem):

npm install @twin.techies/gst-invoice

const { computeInvoice, generateInvoicePDFToFile } = require('@twin.techies/gst-invoice');
// build invoice object as above
await generateInvoicePDFToFile(invoice, 'invoice.pdf', { template: 'corporate' });

RunKit doesn't support writing files, so PDF generation only works in StackBlitz/local. The tax math, validators, and e-invoice JSON export work everywhere.

Features

5 built-in invoice templates: modern, classic, minimal, corporate, compact
Full theming system: customize colors, fonts, density — unlimited variations from any template
Custom templates: register your own via registerTemplate()
Automatic tax split — CGST + SGST for intra-state, IGST for inter-state, decided from state codes
GSTIN validator with checksum verification
HSN/SAC, pincode, state code validation
PDF generation via PDFKit
E-invoice JSON export matching the NIC IRP schema v1.1
Amount in words (Indian numbering: lakh / crore)
Discount, cess, round-off handled correctly
TypeScript-first, ESM + CJS dual build

Install

npm install @twin.techies/gst-invoice
# or
bun add @twin.techies/gst-invoice

Quick start

import {
  computeInvoice,
  generateInvoicePDFToFile,
  toEInvoiceJSON,
} from '@twin.techies/gst-invoice';

const invoice = computeInvoice({
  meta: {
    invoiceNumber: 'INV-2026-001',
    invoiceDate: '2026-05-23',
    dueDate: '2026-06-22',
  },
  seller: {
    name: 'Acme Pvt Ltd',
    gstin: '27AAPFU0939F1ZV',
    stateCode: '27',
    address: {
      line1: '1 MG Road',
      city: 'Mumbai',
      state: 'Maharashtra',
      pincode: '400001',
    },
    email: 'billing@acme.in',
  },
  buyer: {
    name: 'Karnataka Buyers LLP',
    gstin: '29AAACB1234A1ZF',
    stateCode: '29',
    address: {
      line1: '3 Brigade Road',
      city: 'Bengaluru',
      state: 'Karnataka',
      pincode: '560001',
    },
  },
  items: [
    {
      description: 'Custom Widget',
      hsn: '8471',
      quantity: 10,
      unit: 'PCS',
      rate: 1000,
      gstRate: 18,
    },
  ],
});

// Inspect the computed totals
console.log(invoice.totals);
// { taxableValue: 10000, igst: 1800, grandTotal: 11800, ... }

// Render to PDF
await generateInvoicePDFToFile(invoice, './invoice.pdf');

// Export e-invoice JSON for IRP upload
const eInvoice = toEInvoiceJSON(invoice);

Tax logic

The library automatically decides the tax split based on GST state codes of the seller and buyer:

Scenario	Tax applied
Seller stateCode === Buyer stateCode	CGST + SGST (each half of GST rate)
Seller stateCode !== Buyer stateCode	IGST (full GST rate)

API

Tax engine

Function	Description
`computeInvoice(input)`	Validates input, splits taxes, returns computed invoice with line totals and grand total
`computeLine(item, isInterState)`	Computes a single line item's tax
`amountInWordsINR(amount)`	Converts a number to Indian-style words ("One Lakh Twenty-Five Thousand Rupees Only")
`round2(n)`	Standard 2-decimal rounding helper

PDF generation

Function	Description
`generateInvoicePDF(invoice, options?)`	Returns a `Buffer` containing the PDF
`generateInvoicePDFToFile(invoice, path, options?)`	Writes the PDF to disk
`listTemplates()`	Returns names of all registered templates
`registerTemplate(name, renderer)`	Register a custom template

Templates

5 built-in templates:

Name	Style	Best for
`modern` (default)	Clean sans-serif, blue accent bar, alternating row colors	SaaS, agencies, modern businesses
`classic`	Times-Roman serif, bordered boxes, traditional Indian invoice look	Retail, manufacturing, traditional businesses
`minimal`	Pure black & white, lots of whitespace, no chrome	Freelancers, consultants, designers
`corporate`	Dark filled header, formal structure, large company name	Enterprise, B2B, formal billing
`compact`	Dense layout, 7pt font, inline totals	Wholesale, many line items, expense reports

await generateInvoicePDFToFile(invoice, 'invoice.pdf', {
  template: 'corporate',
});

Theming

Override any colors, fonts, or density on top of any template:

await generateInvoicePDFToFile(invoice, 'invoice.pdf', {
  template: 'minimal',
  theme: {
    primary:   '#065f46',         // brand color (accents, header bars)
    accent:    '#10b981',         // secondary accent
    text:      '#111827',         // body text
    muted:     '#6b7280',         // labels, captions
    border:    '#e5e7eb',         // dividers
    rowAlt:    '#f9fafb',         // zebra-stripe rows
    fontHeader: 'Helvetica-Bold', // or 'Times-Bold' | 'Courier-Bold'
    fontBody:   'Helvetica',      // or 'Times-Roman' | 'Courier'
    density:    'compact',        // 'compact' | 'normal' | 'spacious'
    showAmountInWords: true,
  },
});

This means each of the 5 templates × 3 densities × any color combination = effectively unlimited visual variations.

Custom templates

import { registerTemplate, generateInvoicePDF } from '@twin.techies/gst-invoice';

registerTemplate('my-brand', (ctx) => {
  const { doc, invoice, theme, margin, width } = ctx;
  doc.font('Helvetica-Bold').fontSize(20).text('My Company', margin, margin);
  // ... draw the rest using PDFKit
});

await generateInvoicePDF(invoice, { template: 'my-brand' });

PDFOptions:

{
  template?: 'modern' | 'classic' | 'minimal' | 'corporate' | 'compact' | string;
  theme?: Partial<Theme>;
  size?: 'A4' | 'LETTER';        // default 'A4'
  margin?: number;                // default 36
}

E-invoice

Function	Description
`toEInvoiceJSON(invoice)`	Returns NIC IRP v1.1 schema JSON. You upload this to the IRP yourself (or via a GSP).

Validators

Function	Description
`isValidGSTIN(gstin)`	Format + checksum + state-code validation
`extractStateCodeFromGSTIN(gstin)`	Returns the 2-digit state code
`isValidHSN(hsn)`	Validates 4–8 digit HSN/SAC
`isValidPincode(pin)`	Validates 6-digit Indian pincode format
`isValidStateCode(code)`	Validates GST state code

State codes

Function	Description
`GST_STATE_CODES`	Map of `'27' → 'Maharashtra'` etc.
`getStateName(code)`	Code → state name
`getStateCode(name)`	State name → code
`isSameState(a, b)`	Boolean comparison

Types

interface InvoiceInput {
  meta: {
    invoiceNumber: string;
    invoiceDate: string;        // ISO date string
    dueDate?: string;
    placeOfSupply?: string;
    reverseCharge?: boolean;
    documentType?: 'INV' | 'CRN' | 'DBN';
  };
  seller: Party;
  buyer: Party;
  shipTo?: Party;
  items: LineItem[];
  currency?: string;
  notes?: string;
  termsAndConditions?: string;
  logoPath?: string;
}

interface LineItem {
  description: string;
  hsn: string;
  quantity: number;
  unit?: string;
  rate: number;
  gstRate: number;
  discount?: number;
  cess?: number;
}

Roadmap

v0.2 — Logo rendering, more templates (receipt-style, letterhead, certificate)
v0.3 — QR code embedding (mandatory for e-invoice for businesses with turnover > ₹5cr)
v0.4 — Bilingual (English + Hindi/regional) labels
v0.5 — Optional integration with @twin.techies/india-pincode for address validation

Disclaimer

This library helps generate GST-compliant invoice formats based on CGST Rules 2017 and the NIC e-invoice schema v1.1 as publicly published by the Government of India. Users are responsible for:

Ensuring tax rate accuracy (GST rates change — verify with current CBIC notifications)
Submitting invoices to the GST portal / IRP as required
Compliance with current GST regulations applicable to their business

This package is not affiliated with the Government of India, GSTN, or NIC. It is not a GSP (GST Suvidha Provider) — it does not transmit invoices to government systems on your behalf.

License

MIT