Parcel Transcrypt Transformer

1.0.3 verified Fri May 01 auth: no javascript

A Parcel v2 transformer plugin that converts Python files to JavaScript using the Transcrypt transpiler. Version 1.0.3 is current, with no active release cadence. Unlike other Python-to-JS bridges, this integrates directly with Parcel's build pipeline, enabling bundling, code splitting, and HMR. Requires Transcrypt (Python transpiler) installed in a virtual environment; Python version must match Transcrypt version. Supports custom CLI arguments and output directory configuration.

Common errors

error Error: Cannot find module 'parcel-transformer-transcrypt' ↓

cause Package not installed or not listed in devDependencies

fix

Run npm install parcel-transformer-transcrypt --save-dev

error Module script failed because the module is not a valid JavaScript module ↓

cause Python file not transpiled correctly, possibly due to version mismatch

fix

Check Python & Transcrypt versions are compatible (3.9 with 3.9). Re-run build with --verbose.

error Transcrypt: error: unrecognized arguments: --outdir ↓

cause Using Transcrypt 3.7 which doesn't support --outdir

fix

Upgrade to Transcrypt 3.9+ or remove --outdir from arguments.

Warnings

gotcha Python version must match Transcrypt version (e.g., Python 3.9 with Transcrypt 3.9, Python 3.7 with Transcrypt 3.7.16). Mismatch causes transpilation errors. ↓

fix Use compatible Python/Transcrypt versions as documented.

deprecated Transcrypt 3.7 is outdated and may have security vulnerabilities. Use Python 3.9 + Transcrypt 3.9+. ↓

fix Upgrade to Python 3.9 and Transcrypt 3.9 or later.

gotcha The --outdir argument is ignored for Transcrypt 3.7. Output directory customization only works with 3.9 and above. ↓

fix Use Transcrypt 3.9+ for --outdir support.

gotcha The transformer automatically detects Python and Transcrypt versions by running `python --version` and `transcrypt --help`. If multiple Python versions are installed, it may pick the wrong one. ↓

fix Ensure `python` in PATH points to the correct version, or set 'transcryptVersion' in package.json config.

gotcha Transcrypt must be installed in a Python virtual environment, not globally. The transformer assumes 'python' and 'transcrypt' commands are available in the build environment. ↓

fix Activate the virtual environment before running Parcel, or specify full path in 'command' config.

Install

npm install parcel-transformer-transcrypt

yarn add parcel-transformer-transcrypt

pnpm add parcel-transformer-transcrypt

Imports

default (plugin registration)

wrong

import parcelTransformerTranscrypt from 'parcel-transformer-transcrypt'

correct

no JavaScript import needed; configure in .parcelrc

This is a Parcel transformer plugin, not a library. No JS imports required.

Parcel config (JSON)

wrong

{
  "plugins": ["parcel-transformer-transcrypt"]
}

correct

{
  "transformers": {
    "*.py": ["parcel-transformer-transcrypt"]
  }
}

Configure in .parcelrc under transformers, not plugins.

Package config (JSON)

wrong

"parcel-transformer-transcrypt": {
  "version": "3.9"
}

correct

"parcel-transformer-transcrypt": {
  "transcryptVersion": "3.9",
  "watchAllFiles": true,
  "command": "python -m transcrypt",
  "arguments": ["--nomin", "--map"]
}

Configuration goes in package.json under 'parcel-transformer-transcrypt' key, not in a separate file.

Quickstart

Sets up a Parcel project with Python-to-JS support: installs parcel and transformer, creates Python file and HTML entry, configures .parcelrc, and runs build.

# Create a basic Python file (example.py)
print('Hello from Python!')

# Initialize project and install dependencies
npm init -y
npm install parcel --save-dev
npm install parcel-transformer-transcrypt --save-dev

# Set up Python virtual environment with Transcrypt (Python 3.9)
python3.9 -m venv venv
source venv/bin/activate
pip install transcrypt

# Configure .parcelrc
cat > .parcelrc << 'EOF'
{
  "extends": ["@parcel/config-default"],
  "transformers": {
    "*.py": ["parcel-transformer-transcrypt"]
  }
}
EOF

# Create an HTML entry that imports the Python module
cat > index.html << 'EOF'
<!DOCTYPE html>
<html><body>
<script type="module" src="./example.py"></script>
</body></html>
EOF

# Build with Parcel
npx parcel build index.html