halal-check

Zero-dependency TypeScript library to check whether food ingredients and E-codes are halal, haram, or doubtful.

Features

• Ingredient lookup - Check any food ingredient by name
• E-code lookup - Check food additive E-codes (E100-E1520)
• Label parser - Parse comma-separated ingredient lists from food labels
• Zero dependencies - No runtime dependencies, works in Node.js and browsers
• TypeScript-first - Full type definitions included
• ESM + CJS - Dual module format support
• Community-maintained data - PR-friendly YAML database with cited sources

Install

npm install halal-check

Usage

import { checkIngredient, checkECode, parseIngredients } from "halal-check";

// Check a single ingredient
const result = checkIngredient("Gelatin");
// { status: "doubtful", reason: "May be derived from...", sources: [...] }

// Check an E-code
const ecode = checkECode("E120");
// { status: "haram", reason: "Derived from crushed cochineal...", sources: [...] }

// Parse a full ingredient list
const parsed = parseIngredients("Salt, Sugar, E471, Gelatin");
// Returns array sorted by severity (haram > doubtful > unknown > halal)

API

checkIngredient(name: string): IngredientResult

Look up a food ingredient by name. Case-insensitive with diacritics normalization.

checkECode(code: string): IngredientResult

Look up a food additive by E-code (e.g. "E471"). Case-insensitive.

parseIngredients(text: string): ParseResult[]

Parse a comma-separated ingredient list and check each item. Results are sorted with the most severe status first.

Types

type HalalStatus = "halal" | "haram" | "doubtful" | "unknown";

interface IngredientResult {
  name: string;
  status: HalalStatus;
  reason: string;
  sources: string[];
}

interface ParseResult {
  raw: string;
  normalized: string;
  result: IngredientResult;
}

REST API

A free REST API is available, powered by Cloudflare Workers.

Endpoints

Check an ingredient

curl "https://halal-check.YOUR_DOMAIN/api/v1/ingredient?name=Gelatin"

{
  "name": "Gelatin",
  "status": "doubtful",
  "reason": "May be derived from halal or haram sources...",
  "sources": ["..."]
}

Check an E-code

curl "https://halal-check.YOUR_DOMAIN/api/v1/ecode?code=E120"

{
  "name": "E120",
  "status": "haram",
  "reason": "Derived from crushed cochineal insects...",
  "sources": ["..."]
}

Parse an ingredient list

curl -X POST "https://halal-check.YOUR_DOMAIN/api/v1/ingredients" \
  -H "Content-Type: application/json" \
  -d '{"text": "Salt, Sugar, E471, Gelatin"}'

Health check

curl "https://halal-check.YOUR_DOMAIN/api/v1/health"

Note: The API domain will be updated once the Cloudflare Worker is deployed.

Web App

A web-based ingredient checker is included in the web/ directory, built with Preact + Vite.

Contributing

See CONTRIBUTING.md for guidelines on adding ingredients, E-codes, and submitting changes.

Sponsorship

If you find this project useful, please consider sponsoring to help maintain the database and keep the API free.

License

MIT