Babel.transform(); the source it passes is parsed and printed as data and is never executed by the transform.
Overview
Quick Start
Security Model
TheBabel global holds functions of the host, which the enclave hands to the script like any other function in globals. @babel/standalone is loaded into the host realm and runs there, with the host’s intrinsics and the host’s authority. It is called from a separate VM context, and what that context provides is the timeout of the call: it is not an isolation boundary, and it takes nothing away from Babel. A defect in Babel’s parser or in a preset would be a defect in host code. A host that needs Babel isolated from its process runs the enclave in a process of its own.
What a script can make Babel do is restricted by what the wrapper passes on and checks:
Configuration
Security Levels
Each security level provides different limits for Babel transforms:Creating a Babel Enclave
Transform API
Inside the enclave, theBabel global provides a restricted transform API:
Transform Options
Timeout
The transform timeout of the security level applies to each transform, not to an execution: a script that callsBabel.transform() several times, or Babel.transformMultiple() with several files, gets the timeout for every call and for every file. A transform that runs into it fails with Babel transform timed out after <timeout>ms.
Multiple Files
Babel.transformMultiple(files, options) transforms a set of files that import each other and returns { files, dependencies, warnings, rewrittenImports }:
- A file name is at most 255 characters, relative, without
.., made of letters, digits,_,-,/and., and ends in.ts,.tsx,.js,.jsx,.mjs,.cjs,.mtsor.cts. Any other name is refused. - The number of files and the total input and output size are limited by security level (3 files at
STRICT, 10 atSECURE, 25 atSTANDARD, 100 atPERMISSIVE). dependencieslists each local file a file imports once, however many imports name it.
Import Rewriting
WithimportRewrite: { enabled: true, cdnBaseUrl, packageVersions } the transformed code has its imports of npm packages rewritten to URLs below cdnBaseUrl:
- Only allowed packages can be imported: the ones in
allowedPackageswhen that list is given, otherwise the ones named inpackageVersions. An import of another package fails the transform. This holds for import declarations, re-exports and dynamicimport(). - A dynamic
import('pkg')of an allowed package is rewritten like a static import. A dynamic import whose specifier is not written as a string (a string literal, or a template literal without substitutions) cannot be checked and is refused. - Local imports (
./foo,../bar) are left as they are by default. cdnBaseUrlmust be an HTTPS URL without credentials, query or fragment, and a version is a version number, range or tag without path or URL characters.
importRewrite to Babel.transform() itself chooses its own allowlist, so there the rewrite is a convenience and restricts nothing: treat the output as the script’s own text.
Common Use Cases
Transform React Components
Transform TypeScript + JSX
Tool Integration for Dynamic Components
Error Handling
The message of a failed transform isBabel transform failed: followed by Babel’s message with host paths and stack locations removed, cut to 2,000 characters (Babel quotes the source around a syntax error, so its message can be as long as the source):
Common Errors
Performance
Babel transforms are optimized with context caching:Performance Tips
- Batch transforms - Transform multiple components in a single enclave run
- Reuse enclave - Don’t create/dispose for each transform
- Minimize types - Complex TypeScript types increase transform time
- Use STANDARD level - Good balance of security and performance
Direct API (Outside Enclave)
For server-side use without the full enclave sandbox, usecreateRestrictedBabel:
Related
- Overview - Enclave introduction
- Security Levels - Security profiles
- AgentScript Preset - AST validation for enclave code
- Tool System - Integrating tools with enclave