ats-resume

CLI tool to generate ATS-friendly PDF resumes from JSON/JSONC data

Installation

npm install -g ats-resume

Requirements

• Node.js 18 or newer.
• No browser or headless Chrome is required. PDFs are rendered entirely in JavaScript with pdfmake, and the Poppins fonts are bundled with the package.

Usage

ats-resume --json                 # Create resume.jsonc template
ats-resume --create               # Generate PDF from the demo data file
ats-resume --create custom.jsonc  # Generate PDF from a custom data file

Which data file is used

• With an explicit argument, that file is used. Relative paths are resolved against the current directory and absolute paths are accepted as given (e.g. ats-resume --create /tmp/my-resume.jsonc).
• Without an argument, resume.jsonc is preferred. If only resume.json exists, it is used instead.
• A .json file works exactly like a .jsonc file.

Data file format

The resume data lives in a .jsonc file — JSON with comments. Both .json and .jsonc files are accepted, and a plain .json file keeps working unchanged.

In a .jsonc file you may use:

• // line comments
• /* ... */ block comments
• trailing commas before } or ]

{
  // The name printed at the top of the resume
  "personalInfo": {
    "fullName": "Fatema Jannat",
    "nickname": "Fatema",
    "email": "[email protected]",
    // Optional profile photo
    "image": "./photo.png",
    "imageShape": "square"
  },

  /* Work history. Set "show_resume": false to hide an entry from the PDF. */
  "experience": [
    {
      "title": "Software Engineer",
      "company": "Example Inc",
      "startDate": "Jan 2024",
      "current": true,
    },
  ],
}

Any entry with "show_resume": false is excluded from the generated PDF, and sections you do not need can simply be deleted.

Validation and error messages

Before generating the PDF, the data file is checked. If something is wrong, the command stops and prints the JSON path, the section and entry, what is missing, and a hint for fixing it.

Required fields:

• personalInfo.fullName, personalInfo.nickname, and personalInfo.email
• The identifying fields of each entry, for example title and company for experience, institution and degree for education, and name and category for skills

Entries with "show_resume": false are not printed, so their required fields are not checked.

Syntax mistakes are reported too: a missing comma, colon, double quote, brace, or bracket (and an unterminated comment) shows the line and column, the JSON path, the reason, a hint, and a short code snippet with a caret under the problem.

Features

• Generate ATS-friendly PDF resumes from JSON/JSONC data
• Pure-JavaScript PDF rendering with pdfmake (no browser download)
• Bundled Poppins fonts for consistent output offline
• Demo JSONC generation for quick start
• Support for custom JSON/JSONC input files
• Comments in the data file
• Optional profile photo in the top-right corner of the header
• Professional, clean output formatting

Profile photo

Add an optional image field to personalInfo in your data file:

{
  "personalInfo": {
    "fullName": "Fatema Jannat",
    "nickname": "Fatema",
    "image": "./photo.png",
    "imageShape": "square"
  }
}

• Accepts a local path (relative to the data file, or absolute), an https:// URL, or a data: URI.
• Supported formats: .png, .jpg, .jpeg, and .svg. .webp and .gif are skipped with a warning because PDF cannot embed them directly.
• The photo is rendered in the top-right corner, and the contact details wrap into two rows to fit.
• Local files are inlined into the PDF, so the resume can still be built from another working directory.
• Omit the field (or set it to "") for the original single-row header layout.

Photo shape

imageShape controls how the photo is clipped:

| Value | Result | | --- | --- | | square | Hard-edged rectangle (96×116) | | rounded | Rectangle with soft 8px corners | | circle | Circular crop, slightly larger at 104×104 to read well |

• Optional. Omit it and the default circle is used; an unrecognised value also falls back to circle without warning.
• Common synonyms are accepted (round/oval → circle, rect/rectangle → square) and matching is case- and whitespace-insensitive.

License

MIT