or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

browser.md cli.md compilation.md index.md parsing.md registration.md repl.md utilities.md

tile.json

File Registration & Extensions

Registration system for seamless integration with Node.js require() system, enabling direct importing of CoffeeScript files without manual compilation.

Capabilities

Register Function

Registers CoffeeScript file extensions with Node.js require.extensions system to enable automatic compilation.

/**
 * Register CoffeeScript file extensions with Node.js
 * Enables require() to work directly with .coffee, .litcoffee, and .coffee.md files
 */
function register(): void;

Usage Examples:

const CoffeeScript = require('coffeescript');

// Register CoffeeScript extensions
CoffeeScript.register();

// Now you can require CoffeeScript files directly
const myModule = require('./my-module.coffee');
const literateModule = require('./docs.litcoffee');
const markdownModule = require('./readme.coffee.md');

Alternative Registration:

// Direct registration without importing main module
require('coffeescript/register');

// Now CoffeeScript files can be required
const app = require('./app.coffee');

File Extensions

Supported file extensions for CoffeeScript files that will be automatically compiled when required.

/**
 * Array of supported CoffeeScript file extensions
 */
const FILE_EXTENSIONS: string[]; // ['.coffee', '.litcoffee', '.coffee.md']

Usage Examples:

const CoffeeScript = require('coffeescript');

console.log(CoffeeScript.FILE_EXTENSIONS);
// Output: ['.coffee', '.litcoffee', '.coffee.md']

// Check if file is a supported CoffeeScript file
function isCoffeeFile(filename) {
  return CoffeeScript.FILE_EXTENSIONS.some(ext => filename.endsWith(ext));
}

Registration Module (`coffeescript/register`)

The registration module automatically configures Node.js to handle CoffeeScript files and provides additional integration features.

Automatic Features

When require('coffeescript/register') is loaded, it automatically:

Registers File Extensions: Adds handlers for .coffee, .litcoffee, and .coffee.md files
Patches child_process.fork: Enables forking CoffeeScript files directly
Enables Source Maps: Configures stack trace patching for better debugging
Handles Multi-dot Extensions: Supports complex extensions like .coffee.md

Module Loading Process

// When you require a .coffee file after registration:
const myModule = require('./math.coffee');

// Behind the scenes:
// 1. Node.js detects .coffee extension
// 2. CoffeeScript reads the file content
// 3. Compiles CoffeeScript to JavaScript  
// 4. Executes compiled JavaScript
// 5. Returns module.exports result

Source Map Integration

The registration system automatically enables source map support for better debugging:

require('coffeescript/register');

// Now errors in CoffeeScript files show original line numbers
require('./buggy-module.coffee'); // Error traces point to .coffee file

Child Process Integration

CoffeeScript registration patches child_process.fork to handle CoffeeScript files:

require('coffeescript/register');
const { fork } = require('child_process');

// Fork CoffeeScript files directly
const child = fork('./worker.coffee', ['arg1', 'arg2']);

// Equivalent to:
// const child = fork('/path/to/coffee', ['./worker.coffee', 'arg1', 'arg2']);

Literate CoffeeScript Support

CoffeeScript supports literate programming through .litcoffee and .coffee.md files:

# My Literate CoffeeScript Module

This is a markdown document that contains executable CoffeeScript code.

## Implementation

Here's our main function:

    square = (x) -> x * x
    
    add = (a, b) -> a + b

## Usage

The functions can be used like this:

    console.log square 5  # 25
    console.log add 3, 4  # 7

## Exports

    module.exports = { square, add }

Registration handles literate files automatically:

require('coffeescript/register');

// Both work the same way
const math1 = require('./math.litcoffee');
const math2 = require('./math.coffee.md');

Manual File Loading

For advanced use cases, you can manually load and compile CoffeeScript files:

/**
 * Internal file loading function used by registration system
 * @param module - Node.js module object
 * @param filename - Path to CoffeeScript file
 */
function loadFile(module: NodeModule, filename: string): void;

const CoffeeScript = require('coffeescript');
const fs = require('fs');

// Manual compilation and loading
function loadCoffeeModule(filename) {
  const source = fs.readFileSync(filename, 'utf8');
  const compiled = CoffeeScript.compile(source, { 
    filename,
    bare: true 
  });
  
  const module = { exports: {} };
  const fn = new Function('module', 'exports', 'require', '__filename', '__dirname', compiled);
  fn(module, module.exports, require, filename, path.dirname(filename));
  
  return module.exports;
}

Error Handling

Registration provides helpful error messages for missing files and syntax errors:

require('coffeescript/register');

try {
  require('./nonexistent.coffee');
} catch (error) {
  // Standard Node.js MODULE_NOT_FOUND error
  console.log(error.code); // 'MODULE_NOT_FOUND'
}

try {
  require('./invalid-syntax.coffee');
} catch (error) {
  // CoffeeScript syntax error with file context
  console.log(error.filename); // Path to .coffee file
  console.log(error.location); // Line/column information
}

Performance Considerations

Compilation Caching: Compiled modules are cached by Node.js like regular JavaScript modules
Source Map Caching: Source maps are cached separately for stack trace patching
File Watching: No automatic recompilation; use development tools for file watching
Production Usage: Consider pre-compiling for production to avoid runtime compilation overhead

// Check if module is already cached
const moduleId = require.resolve('./my-module.coffee');
const isCached = moduleId in require.cache;

// Clear cache for development hot-reloading
delete require.cache[moduleId];
const freshModule = require('./my-module.coffee');