@typecad/jlcpcb-parts

Intelligent fuzzy search for JLCPCB basic and preferred electrical components with CLI interface. This TypeScript-based npm package provides smart component search capabilities by automatically managing a local database of JLCPCB parts and offering natural language search with intelligent parameter matching.

Dependencies

This package uses CDFER/jlcpcb-parts-database which provides a daily CSV download of all basic and preferred parts. That project depends on yaqwsx/jlcparts. Please consider supporting them.

Features

• 🔍 Intelligent Fuzzy Search: Find components using natural language descriptions
• 📦 Automatic Database Management: Downloads and caches JLCPCB components database
• ⚡ Fast CLI Interface: Quick command-line searches with formatted output
• 🎯 Smart Parameter Parsing: Recognizes electrical values, packages, tolerances, and more
• 📊 Scored Results: Get ranked results with match explanations
• 🔄 Auto-Updates: Keeps component database fresh (24-hour cache)
• 🎨 Multiple Output Formats: Detailed, compact, table, or JSON display options
• 🔧 Programmatic Integration: JSON output for scripting and automation

Installation

Global Installation (Recommended)

npm install -g @typecad/jlcpcb-parts

After global installation, you can use the jlcpcb-search command from anywhere:

jlcpcb-search "10k resistor 0603"

Local Installation

npm install @typecad/jlcpcb-parts

Quick Start

Basic Search

# Search for a 10kΩ resistor in 0603 package
jlcpcb-search "10k resistor 0603"

# Search for a 100µF capacitor rated for 16V
jlcpcb-search "100uF capacitor 16V"

# Search for buttons
jlcpcb-search "SPST button"

Advanced Usage

# Use table format for compact display
jlcpcb-search "LM358 op amp" --format table

# Sort by manufacturer and show 1 result
jlcpcb-search "ceramic capacitor 0402" --sort manufacturer --limit 1

# Compact format for quick overview
jlcpcb-search "LED red 0603" --format compact

# JSON format for programmatic use
jlcpcb-search "10k resistor" --format json

Usage

Command Line Interface

jlcpcb-search [options] <search query>

Options:
  -h, --help                Display help message
  -v, --version             Display version information
  -f, --format <format>     Output format: detailed, compact, table, or json (default: detailed)
  -s, --sort <field>        Sort by: score, lcsc, manufacturer, or package (default: score)
  -l, --limit <number>      Limit number of results (default: 5)

Search Query Examples

The tool understands natural language descriptions and can parse various electrical parameters:

Resistors

jlcpcb-search "10k resistor 0603"           # 10kΩ resistor in 0603 package
jlcpcb-search "1M ohm 1% 0805"              # 1MΩ resistor with 1% tolerance
jlcpcb-search "220 ohm thick film"          # 220Ω thick film resistor

Capacitors

jlcpcb-search "100nF 50V X7R 0603"          # 100nF ceramic capacitor
jlcpcb-search "10uF 16V tantalum"           # 10µF tantalum capacitor
jlcpcb-search "1mF electrolytic 25V"        # 1mF electrolytic capacitor

Inductors

jlcpcb-search "10uH inductor 0805"          # 10µH inductor
jlcpcb-search "100nH ferrite bead"          # 100nH ferrite bead

ICs and Active Components

jlcpcb-search "LM358 op amp"                # LM358 operational amplifier
jlcpcb-search "STM32F103 microcontroller"   # STM32F103 microcontroller
jlcpcb-search "AMS1117 voltage regulator"   # AMS1117 voltage regulator

Connectors and Mechanical

jlcpcb-search "USB"                         # IC
jlcpcb-search "2.54mm header male"          # 2.54mm pin headers
jlcpcb-search "tactile switch 6x6"          # Tactile switches

Output Formats

Detailed Format (Default)

Shows complete component information with match explanations:

Found 3 matching components:

1. C25804 - 10kΩ ±1% 0603 Thick Film Resistor
   Manufacturer: UNI-ROYAL(Uniroyal Elec)
   Part Number: 0603WAF1002T5E
   Package: 0603
   Match Score: 95.0
   Match Details: Exact resistance match (100 pts), Package match (80 pts), Tolerance match (70 pts)

Compact Format

One-line summary per component:

jlcpcb-search "10k resistor" --format compact

1. C25804 - 10kΩ ±1% 0603 Thick Film Resistor... - 0603 - 95.0
2. C25879 - 10kΩ ±5% 0805 Thick Film Resistor... - 0805 - 87.5

Table Format

Structured table view:

jlcpcb-search "capacitor 0603" --format table

#   LCSC     Manufacturer     Part Number      Package Score  Description
--- -------- ---------------- ---------------- ------- ------ -----------
1   C14663   Samsung Electro  CL10B104KB8N...  0603    92.0   100nF 50V X7R...
2   C1608    Samsung Electro  CL10A105KB8N...  0603    89.5   1µF 25V X5R...

JSON Format

Machine-readable JSON output for programmatic integration:

jlcpcb-search "10k resistor 0603" --format json

[
  {
    "lcsc": "25804",
    "manufacturer": "UNI-ROYAL(Uniroyal Elec)",
    "partNumber": "0603WAF1002T5E",
    "description": "10kΩ ±1% 0603 Thick Film Resistor",
    "package": "0603",
    "score": 95.0,
    "matchSummary": "Exact resistance match (100 pts), Package match (80 pts)"
  },
  {
    "lcsc": "25879",
    "manufacturer": "UNI-ROYAL(Uniroyal Elec)",
    "partNumber": "0805WAF1002T5E",
    "description": "10kΩ ±5% 0805 Thick Film Resistor",
    "package": "0805",
    "score": 87.5,
    "matchSummary": "Exact resistance match (100 pts), Package match (40 pts)"
  }
]

JSON Format Features:

• Clean Output: No formatting, colors, or progress indicators
• Machine-Readable: Valid JSON for easy parsing by scripts and applications
• Complete Data: All component information included in structured format
• Empty Results: Returns empty array [] when no components found
• Error Handling: Errors output as JSON objects with error information

JSON Error Response Format:

{
  "error": true,
  "message": "No search query provided",
  "code": "MISSING_QUERY"
}

How It Works

Automatic Database Management

The tool automatically manages the JLCPCB components database:

1. First Run: Downloads the complete JLCPCB components CSV file (~3MB)
2. Caching: Stores the database locally with a timestamp
3. Auto-Update: Downloads the CSV again if it is more than 24 hours old
4. Offline Mode: Works with cached data when network is unavailable

Intelligent Parameter Parsing

The search engine recognizes and parses:

• Electrical Values: 10k, 100nF, 1µH, 3.3V
• Units: Supports all standard electrical units with prefixes
• Packages: 0603, 0805, SOT-23, SOIC-8, etc.
• Tolerances: ±1%, ±5%, +/-10%
• Component Types: X7R, NP0, MLCC, SMD, THT
• Keywords: Manufacturer names, part families, descriptions

Fuzzy Scoring Algorithm

Components are scored based on multiple factors:

• Exact Matches: 100 points per parameter
• Close Matches: 50-90 points for similar values
• Package Matches: 80 points for exact, 40 for similar
• Type Matches: 70 points for component type
• Keyword Matches: 20-50 points for description relevance
• Category: 30 points for matching component category

JSON Mode Behavior

When using the JSON format (--format json), the tool operates in a special mode optimized for programmatic use:

• Clean Output: No progress indicators, status messages, or colored text
• Pure JSON: Only valid JSON is output to stdout
• Error Handling: Errors are formatted as JSON objects with error information
• Exit Codes: Proper exit codes are maintained for error detection
• Performance: Slightly faster execution due to reduced formatting overhead

Programmatic Usage

You can also use the package programmatically in your Node.js applications:

import {
  DataManager,
  ElectricalParameterParser,
  ComponentFuzzyScorer,
  ComponentSearchEngine,
} from "@typecad/jlcpcb-parts";

// Create your own search engine instance
const dataManager = new DataManager();
const parser = new ElectricalParameterParser();
const scorer = new ComponentFuzzyScorer();
const searchEngine = new ComponentSearchEngine(dataManager, parser, scorer);

// Perform searches
const results = await searchEngine.search("10k resistor 0603");
console.log(results);

Configuration

Environment Variables

• JLCPCB_CSV_URL: Custom URL for the JLCPCB CSV file
• JLCPCB_CACHE_DIR: Directory to store cached files (default: current directory)
• JLCPCB_CACHE_HOURS: Cache expiration time in hours (default: 24)

Cache Management

The tool stores cache files in your current directory:

• jlcpcb-components-basic-preferred.csv: Component database
• .jlcpcb-cache-timestamp: Cache timestamp file
• .logs/: Search and error logs

To force a database refresh, delete the timestamp file:

rm .jlcpcb-cache-timestamp

Troubleshooting

Common Issues

No Results Found

No components found matching your search criteria.
Suggestions:
- Try using more general terms (e.g., "capacitor" instead of "ceramic capacitor")
- Check your spelling and try alternative terms
- Remove specific parameters that might be too restrictive
- Try searching for a different package size or value

Solutions:

• Use broader search terms
• Check spelling of component values and types
• Try alternative package sizes (0603 vs 0805)
• Search for component families instead of specific part numbers

Network/Download Issues

Error: Failed to download component database

Solutions:

• Check your internet connection
• Verify firewall settings allow HTTPS connections
• Try again later (server might be temporarily unavailable)
• Use cached data if available

Permission Errors

Error: Permission denied writing cache files

Solutions:

• Run from a directory where you have write permissions
• Check file system permissions
• Try running with elevated privileges (if appropriate)

Debug Mode

Enable verbose logging by setting the log level:

# Set environment variable for debug logging
export JLCPCB_LOG_LEVEL=DEBUG
jlcpcb-search "10k resistor"

Getting Help

• Use jlcpcb-search --help for command-line help
• Review log files in .logs/ directory for detailed error information

Related Projects

• TypeCAD - use TypeScript to create PCBs in KiCAD
• JLCPCB Parts Database - Source of component data

Support

• Buy me a coffee

Made by typeCAD