ats-cv

ATS CV Generator

Professional ATS-optimized CV/Resume PDF generator with multiple templates supporting Turkish and English languages.

Features

• 🎨 5 Professional Templates: Basic HR, Office Manager, Simple Classic, Stylish Accounting, Minimalist Turkish
• 🌍 Multi-language Support: Turkish and English
• 📄 ATS-Optimized: Structured for Applicant Tracking Systems
• 🎯 Flexible Data Structure: Supports both global and Turkey-specific CV formats
• ⚡ TypeScript Support: Full type safety and IntelliSense
• 🔤 Font Support: Built-in Turkish character support with Noto Sans fonts

Installation

npm install ats-cv

Quick Start

import { CVGenerator } from 'ats-cv';

// Define your CV data
const cvData = {
  personalInfo: {
    firstName: 'John',
    lastName: 'Doe',
    email: '[e-mail]',
    phone: '[phone]',
    address: '123 Main St',
    city: 'New York',
    linkedin: 'https://linkedin.com/in/johndoe',
    github: 'https://github.com/johndoe',
    website: 'https://johndoe.dev',
    medium: 'https://medium.com/@johndoe',
    jobTitle: 'Software Engineer',
  },
  objective:
    'Experienced software engineer seeking new challenges in full-stack development.',
  experience: [
    {
      company: 'Tech Corp',
      jobTitle: 'Software Engineer',
      startDate: '2020-01',
      endDate: '2023-12',
      isCurrent: false,
      location: 'New York, NY',
      description:
        'Developed web applications using React and Node.js. Led a team of 3 developers, increased efficiency by 40%',
    },
  ],
  education: [
    {
      university: 'University of Technology',
      degree: 'Bachelor of Science',
      field: 'Computer Science',
      startDate: '2016-09',
      graduationDate: '2020-05',
      location: 'New York, NY',
      details: 'GPA: 3.8/4.0',
    },
  ],
  skills: ['JavaScript', 'TypeScript', 'React', 'Node.js', 'Python'],

  // Global version specific fields
  communication:
    'Excellent written and verbal communication skills in English and Spanish',
  leadership:
    'Led cross-functional teams of 5+ developers on multiple projects',

  // Turkey version fields (optional for all versions)
  technicalSkills: {
    frontend: ['React', 'Vue.js'],
    backend: ['Node.js', 'Python'],
    database: ['PostgreSQL', 'MongoDB'],
    tools: ['Git', 'Docker'],
  },
  projects: [
    {
      name: 'Portfolio Website',
      description: 'Personal portfolio built with React and TypeScript',
      technologies: 'React, TypeScript, Tailwind CSS',
      link: 'https://github.com/johndoe/portfolio',
    },
  ],
  certificates: [
    {
      name: 'AWS Solutions Architect',
      issuer: 'Amazon Web Services',
      date: '2023-08',
    },
  ],
  languages: [
    {
      language: 'English',
      level: 'Native',
    },
    {
      language: 'Spanish',
      level: 'Intermediate',
    },
  ],
  references: [
    {
      name: 'Sarah Johnson',
      company: 'Tech Corp',
      contact: '[e-mail], [phone]',
    },
  ],

  // Version control
  version: 'global',
  language: 'english',
};

// Generate CV
try {
  const result = await CVGenerator.generatePDF({
    templateType: 'basic_hr',
    data: cvData,
  });

  console.log(`Generated: ${result.fileName}`);
  // Save the PDF buffer to file
  require('fs').writeFileSync(result.fileName, result.pdfBuffer);
} catch (error) {
  console.error('CV generation failed:', error);
}

Available Templates

const templates = CVGenerator.getAvailableTemplates();
console.log(templates);

// Output:
[
  {
    id: 'basic_hr',
    name: 'Basic HR Resume',
    description: 'Clean and professional HR-focused resume template',
    supportedVersions: ['global', 'turkey'],
    supportedLanguages: ['turkish', 'english'],
  },
  // ... other templates
];

Data Validation

Validate your CV data before PDF generation:

// Basic validation
const validation = CVGenerator.validateTemplateData('basic_hr', cvData);

if (!validation.isValid) {
  console.error('Validation errors:', validation.errors);
  console.warn('Warnings:', validation.warnings);
} else {
  console.log('Data is valid!');
}

// Template compatibility check
const isCompatible = CVGenerator.isTemplateCompatible(
  'minimalist_turkish',
  'turkey',
  'turkish'
);

if (!isCompatible) {
  console.error(
    'Template not compatible with this version/language combination'
  );
}

Turkey-Specific Features

For Turkey version CVs, additional fields are supported:

const turkishCvData = {
  personalInfo: {
    firstName: 'Ahmet',
    lastName: 'Yılmaz',
    email: '[e-mail]',
    phone: '[phone]',
    address: 'Kadıköy Mahallesi',
    city: 'İstanbul',
    linkedin: 'https://linkedin.com/in/ahmetyilmaz',
    github: 'https://github.com/ahmetyilmaz',
    website: 'https://ahmetyilmaz.dev',
    medium: 'https://medium.com/@ahmetyilmaz',
    jobTitle: 'Yazılım Geliştirici',
  },
  objective:
    'Full-stack geliştirme alanında yeni fırsatlar arayan deneyimli yazılım geliştirici.',

  // Turkey-specific sections
  technicalSkills: {
    frontend: ['React', 'Vue.js', 'Angular'],
    backend: ['Node.js', 'Python', 'Java'],
    database: ['MongoDB', 'PostgreSQL'],
    tools: ['Git', 'Docker', 'AWS'],
  },

  projects: [
    {
      name: 'E-ticaret Platformu',
      description: 'Full-stack web uygulaması',
      technologies: 'React, Node.js, MongoDB',
      link: 'https://github.com/username/project',
    },
  ],

  certificates: [
    {
      name: 'AWS Certified Developer',
      issuer: 'Amazon Web Services',
      date: '2023-06',
    },
  ],

  languages: [
    {
      language: 'İngilizce',
      level: 'İleri Düzey',
    },
  ],

  references: [
    {
      name: 'Jane Smith',
      company: 'Tech Corp',
      contact: '[e-mail], [phone]',
    },
  ],

  // Version control
  version: 'turkey',
  language: 'turkish',
};

TypeScript Support

The package includes comprehensive TypeScript definitions:

import {
  CVTemplateType,
  CVTemplateData,
  CVGenerationOptions,
  CVGenerationResult,
  ValidationResult,
} from 'ats-cv';

const options: CVGenerationOptions = {
  templateType: 'basic_hr',
  data: cvData,
  customFileName: 'my-custom-cv.pdf',
};

const result: CVGenerationResult = await CVGenerator.generatePDF(options);

Advanced Usage

Custom File Names

const result = await CVGenerator.generatePDF({
  templateType: 'basic_hr',
  data: cvData,
  customFileName: 'John_Doe_Software_Engineer.pdf',
});

Comprehensive Validation Example

import { CVGenerator, CVTemplateData } from 'ats-cv';

const cvData: CVTemplateData = {
  personalInfo: {
    firstName: 'John',
    lastName: 'Doe',
    // ... other required fields
  },
  // ... other data
};

// Step 1: Validate data structure
const validation = CVGenerator.validateTemplateData('basic_hr', cvData);
if (!validation.isValid) {
  throw new Error(`Validation failed: ${validation.errors.join(', ')}`);
}

// Step 2: Check template compatibility
const isCompatible = CVGenerator.isTemplateCompatible(
  'basic_hr',
  cvData.version || 'global',
  cvData.language || 'english'
);

if (!isCompatible) {
  throw new Error('Template not compatible with specified version/language');
}

// Step 3: Generate PDF
const result = await CVGenerator.generatePDF({
  templateType: 'basic_hr',
  data: cvData,
});

Using Utilities

import { DateFormatter, shortenUrlForDisplay } from 'ats-cv';

// Format dates
const formatted = DateFormatter.formatDate('2023-06-15'); // "Jun 2023"

// Shorten URLs for PDF display
const shortUrl = shortenUrlForDisplay('https://linkedin.com/in/johndoe');
console.log(shortUrl.displayText); // "linkedin/johndoe"

Error Handling

try {
  const result = await CVGenerator.generatePDF(options);
} catch (error) {
  if (error.message.includes('Validation failed')) {
    // Handle validation errors
    console.error('Invalid CV data:', error.message);
  } else if (error.message.includes('Font file not found')) {
    // Handle font loading errors
    console.error('Font loading failed:', error.message);
  } else {
    // Handle other errors
    console.error('CV generation failed:', error.message);
  }
}

Data Structure & Field Requirements

Overview

The CVTemplateData interface supports both global and Turkey-specific CV formats. All fields except personalInfo core fields are optional, allowing flexible data structures.

Field Requirements Table

Field Category	Field Name	Type	Required	Global	Turkey	Description
Personal Info	firstName	string	✅	✅	✅	First name
	lastName	string	✅	✅	✅	Last name
	email	string	✅	✅	✅	Email address
	phone	string	✅	✅	✅	Phone number
	address	string	✅	✅	✅	Street address
	city	string	✅	✅	✅	City
	github	string?	❌	✅	✅	GitHub profile URL
	linkedin	string?	❌	✅	✅	LinkedIn profile URL
	website	string?	❌	✅	✅	Personal website URL
	medium	string?	❌	✅	✅	Medium profile URL
	jobTitle	string?	❌	✅	✅	Current job title
Core Sections	objective	string?	❌	✅	✅	Career objective/summary
	experience	Array?	❌	✅	✅	Work experience entries
	education	Array?	❌	✅	✅	Education entries
	skills	string[]?	❌	✅	✅	Skills list
Global Fields	communication	string?	❌	✅	✅	Communication skills description
	leadership	string?	❌	✅	✅	Leadership experience description
Turkey Fields	technicalSkills	Object?	❌	✅	✅	Technical skills categorized
	projects	Array?	❌	✅	✅	Project portfolio
	certificates	Array?	❌	✅	✅	Certifications
	languages	Array?	❌	✅	✅	Language proficiencies
	references	Array?	❌	✅	✅	Professional references
Version Control	version	'global'|'turkey'?	❌	✅	✅	CV format version
	language	'english'|'turkish'?	❌	✅	✅	Display language

Detailed Field Specifications

Experience Array Fields

Field	Type	Required	Description
company	string	✅	Company name
jobTitle	string	✅	Position title
startDate	string	✅	Start date (YYYY-MM format)
endDate	string	✅	End date (YYYY-MM format)
isCurrent	boolean	✅	Currently employed flag
location	string	✅	Job location
description	string	✅	Job responsibilities and achievements

Education Array Fields

Field	Type	Required	Description
university	string	✅	Institution name
degree	string	✅	Degree type
field	string	✅	Field of study
startDate	string	✅	Start date (YYYY-MM format)
graduationDate	string	✅	Graduation date (YYYY-MM format)
location	string	✅	Institution location
details	string?	❌	Additional details (GPA, honors, etc.)

Technical Skills Object

Field	Type	Required	Description
frontend	string[]?	❌	Frontend technologies
backend	string[]?	❌	Backend technologies
database	string[]?	❌	Database technologies
tools	string[]?	❌	Development tools

Projects Array Fields

Field	Type	Required	Description
name	string	✅	Project name
description	string	✅	Project description
technologies	string	✅	Technologies used (comma-separated)
link	string?	❌	Project URL/repository

Certificates Array Fields

Field	Type	Required	Description
name	string	✅	Certificate name
issuer	string	✅	Issuing organization
date	string	✅	Issue date (YYYY-MM format)

Languages Array Fields

Field	Type	Required	Description
language	string	✅	Language name
level	string	✅	Proficiency level

References Array Fields

Field	Type	Required	Description
name	string	✅	Reference name
company	string	✅	Reference company
contact	string	✅	Contact information

Validation Rules

Required Field Validation

// Minimal valid CV data
const minimalCV: CVTemplateData = {
  personalInfo: {
    firstName: 'John',
    lastName: 'Doe',
    email: '[e-mail]',
    phone: '[phone]',
    address: '123 Main St',
    city: 'New York',
  },
};

Date Format Validation

• All dates must follow YYYY-MM format
• Examples: '2023-01', '2020-12'
• Invalid: 'Jan 2023', '2023', '01/2023'

URL Format Validation

• All URL fields should include protocol
• Valid: 'https://github.com/username'
• Invalid: 'github.com/username'

Template Compatibility

Template	Supported Versions	Supported Languages	Special Requirements
basic_hr	global, turkey	english, turkish	None
office_manager	global, turkey	english, turkish	None
simple_classic	global, turkey	english, turkish	None
stylish_accounting	global, turkey	english, turkish	None
minimalist_turkish	turkey	turkish	Must use turkey version

Best Practices

Data Organization

• Keep descriptions concise: Aim for 2-3 lines per experience description
• Use action verbs: Start descriptions with strong action verbs
• Quantify achievements: Include numbers and metrics when possible
• Consistent formatting: Use consistent date and URL formats throughout

Performance Tips

• Validate data first: Always use validateTemplateData() before generation
• Optimize assets: Keep font assets in the package for reliable rendering
• Error handling: Implement comprehensive error handling for production use

Localization

• Turkish characters: Automatically handled with Noto Sans fonts
• Date formatting: Dates are formatted according to language setting
• Section headers: Automatically translated based on language field

Requirements

• Node.js >= 18.0.0
• TypeScript >= 4.5 (for TypeScript projects)
• Internet connection (for font loading from Google Fonts)

Font Loading Strategy

The package uses web fonts from Google Fonts to minimize package size:

• Primary fonts: Noto Sans (Regular & Bold) - Excellent Turkish support
• Fallback fonts: Roboto (Regular & Bold) - General web-safe fonts
• Emergency fallback: System Helvetica - Limited Turkish character support

Benefits:

• ✅ Small package size: ~400KB instead of ~3MB
• ✅ Always up-to-date fonts: Google Fonts automatically optimized
• ✅ Better performance: Fonts cached after first download

Trade-offs:

• ⚠️ Internet dependency: Requires connection for first-time font loading
• ⚠️ Offline limitations: Falls back to system fonts without internet

License

MIT

Contributing

Issues and pull requests are welcome on GitHub.

Support

For questions and support, please open an issue on GitHub.