FastLED WASM Development Guidelines

Guidelines for working with the FastLED WASM project, a lightning-fast web compiler with 3-second compile and 1-second deploy times.

Critical Rules

Python Command Execution

**ALWAYS use `uv` to run Python code, NEVER `python` or `python3`**

This project uses `uv` for Python package and environment management. Using `python` directly may use the wrong version or miss dependencies.

Emoji Handling

**ALWAYS use the `EMO()` function for emojis, NEVER hardcode emojis directly**

Windows cmd.exe has poor Unicode support and crashes on raw emojis. The `EMO()` function provides fallback text for systems without emoji support.

Step-by-Step Instructions

1. Running Python Code

Use `uv run` for ALL Python execution:

```bash

Running scripts

uv run <script.py>

Running modules

uv run -m <module>

Explicit Python invocation (if needed)

uv run python <script.py>

```

**Examples:**

2. Testing Workflow

Run unit tests using the project's test script:

```bash

bash test

```

For manual testing, always prefix Python commands with `uv run`.

3. Using Emojis in Code

Import and use the `EMO()` function for all emoji output:

```python

from fastled.emoji_util import EMO

Warning messages

print(f"{EMO('⚠️', 'WARNING:')} Debug mode detected")

Success messages

print(f"{EMO('✅', 'SUCCESS:')} Build completed")

Error messages

print(f"{EMO('❌', 'ERROR:')} Compilation failed")

Info messages

print(f"{EMO('ℹ️', 'INFO:')} Starting process")

Playwright/browser context

print(f"{EMO('🎭', '*')} Browser launched")

Package installation

print(f"{EMO('📦', '*')} Installing dependencies")

```

For Unicode-safe printing:

```python

from fastled.emoji_util import safe_print

safe_print("Text with potential Unicode issues")

```

4. Development Workflow

1. **Install dependencies:**

```bash

uv add <package>

```

2. **Run scripts:**

```bash

uv run <script>

```

3. **Virtual environment:**

- Let `uv` manage the environment automatically

- No need to manually activate/deactivate

5. Updating Existing Scripts

When you find scripts using `python` or `python3`, update them to use `uv run`:

```bash

Before

python build.py

After

uv run build.py

```

6. Documentation

When documenting Python usage:

Common Patterns

Command Execution

Emoji Usage

Rationale

**Why `uv`?**

**Why `EMO()` function?**

Important Notes