parcel-transformer-transcrypt

A Python to JavaScript transformer for Parcel v2 using the Transcrypt transpiler

If you find a problem with this Parcel transformer, please submit an issue on GitHub and help make it better.

If you just have a question about how to use it, you can also post a message in GitHub discussions.

Installation

This Parcel transformer can be installed with npm or yarn:

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

To get the latest unpublished version, you can also install it directly from the GitHub repository:

npm install https://github.com/TranscryptOrg/parcel-transformer-transcrypt --save-dev

Dependencies

Obviously Parcel v2 must be installed:

npm install parcel -D

This plugin also requires installation of the Transcrypt transpiler. In order for Transcrypt to properly parse the AST of your Python code, the version of Python you use with Transcrypt must match the version of Transcrypt it was designed for.

It is recommended to install Transcrypt into a virtual environment for your project. This can be accomplished with the following commands:

For Python 3.9:

python3.9 -m venv venv
. ./venv/bin/activate
python -m pip install transcrypt

For Python 3.7:

python3.7 -m venv venv
. ./venv/bin/activate
python -m pip install transcrypt==3.7.16

Note that when run, before the build process starts, this transformer will automatically detect the version of Python and Transcrypt being used by running the following commands in the background:

• python --version
• transcrypt --help

To bypass this auto-detect behavior, you can explicitly specify the Transcrypt version in the package.json file as indicated in the next section.

Configuration

You will need to create a .parcelrc file in the same folder as the package.json file to let Parcel know how to handle the Python files:

.parcelrc

{
  "extends": ["@parcel/config-default"],
  "transformers": {
    "*.py": ["parcel-transformer-transcrypt"]
  }
}

To override the default settings for Transcrypt, you can add a "parcel-transformer-transcrypt" key to the package.json file with the desired CLI configuration information:

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

The "transcryptVersion", "watchAllFiles", "command", and "arguments" keys are all optional. Default values will be used if not supplied.

If the watchAllFiles key is missing or set to true, all Python files that are processed by Transcrypt will be added to Parcel's file watch. If this key is set to false, only the initial entry point file will be watched.

Transcrypt normally puts the files it generates in a folder called __target__ that is created in the same folder as the source files you are processing. This default behavior may not be desired in many cases.

If you are using Transcrypt 3.9 however, this Parcel transformer will put Transcrypt's generated files in a folder named .build that will be created in the root folder of the project (where the package.json file resides and where you run npm commands from). You can override the location of this build folder by adding an argument to the configuration as shown above:

    "arguments": [
      "--nomin",
      "--map",
      "--outdir src/__target__"  
    ]

The output folder you specify in the arguments should be relative to the project root folder.

Note that the --outdir directive is not valid for Transcrypt version 3.7 and will be ignored in that case.

You can also set up build scripts in the package.json file for Parcel that might look similar to this:

  "scripts": {
    "start": "NODE_ENV=development parcel --log-level info src/index.html --dist-dir dist/dev --port 8080",
    "build": "NODE_ENV=production parcel build --log-level info src/index.html --no-source-maps --dist-dir dist/prod --no-cache"
  }

The npm start script would run Parcel in development mode that starts up a development web server and watches source files for changes.

The npm run build script builds the application for production then exits.

FAQ

• What does this Parcel plugin do?
  Instead of having to run Transcrypt manually and then use those generated JavaScript files as the input to what you want to bundle with Parcel, you can just run Parcel and it will run Transcrypt for you when it sees a file with a .py file extension.

  For example, if Parcel sees a Python file specified as the src in an HTML script tag, it will have Transcrypt generate the Javascript file and then automatically update the HTML script tag with the name of the generated JavaScript file.

  As a bonus, anytime you make a change to one of your Python files while Parcel has it's development server running in "watch" mode, your updated Python files will automatically be re-transpiled by Transcrypt.

• How does this plugin compare to the one for Parcel v1?
  It is very similar:

  • It mostly works seamlessly with the default configuration
  • It installs as a JavaScript development dependency
  • The configuration can be customized by adding entries to package.json

  But there are also a few differences:

  • The output folder is configurable
  • Parcel file watch works on all transpiled Python files in development mode and not just the entry point
  • It doesn't need to be patched before using it :-)

• What if I don't want to use Transcrypt?
  Then you will have to use a different Parcel transformer for Python other than this one. It is a hard dependency.

Notes

This has been tested with:

• Linux Mint 19/Ubuntu 18
• Windows 10
• macOS Monterey
• Python/Transcrypt version 3.7 & 3.9
• Node versions 14, 15, 16
• npm versions 6, 7, 8
• parcel versions 2.2, 2.4

If you are using Linux and start getting errors stating "No space left on device", see the Parcel website for how to fix it.