public/strudel

Fork 0

Files

Michael Czechowski b427c2b6dc update blog post to include hugo specific front matter

2025-09-27 21:51:14 +02:00

8.9 KiB

Raw Blame History

title, date, draft, tags, categories, build, list, publishResources

title

date

draft

Mastering Strudel: A Reproducible Development Environment with Nix

Strudel is a fascinating JavaScript-based live coding environment that brings the power of TidalCycles to the web. As developers and musicians exploring algorithmic music composition, we've discovered that setting up a proper development environment is crucial for productive work. In this post, we'll dive deep into our Nix-based setup that makes Strudel development reproducible, reliable, and collaborative.

Why Nix for Strudel Development?

Traditional development environments often suffer from the "works on my machine" syndrome. Dependencies drift, versions conflict, and onboarding new contributors becomes a chore. Nix solves these problems by providing declarative, reproducible environments.

Our Strudel development setup uses:

Nix Flakes for pinned, reproducible dependencies
Git submodules to track the official Strudel repository
Makefile for convenient command shortcuts
Comprehensive guidelines for AI-assisted development

Getting Started: The Complete Setup

Prerequisites

Before diving in, ensure you have:

Nix package manager (version 2.4+)
Git for version control

Step-by-Step Setup

Clone the repository:

git clone <your-strudel-dev-repo-url>
cd strudel

Initialize git submodules:
```
make submodules-init submodules-update
```
This pulls in the official Strudel codebase as a submodule in the src/ directory.
Enter the development environment:
```
make shell
```
This launches a Nix shell with Node.js 20, pnpm, and git pre-configured.
Install dependencies:
```
make install
```
This runs pnpm install within the Nix environment, ensuring consistent package versions.
Start the development server:
```
make dev
```
The Strudel REPL will be available at http://localhost:5173.

Understanding the Project Structure

strudel/
├── src/                    # Strudel codebase (git submodule)
├── AGENTS.md              # Guidelines for AI assistants
├── Makefile               # Development shortcuts
├── flake.nix              # Nix development environment
├── flake.lock             # Nix flake lockfile
└── README.md              # This file

The src/ directory contains the actual Strudel monorepo as a git submodule. This approach ensures we always work with a specific, tested version of Strudel while keeping our development environment separate.

Workflow Mastery with Makefile

Our Makefile provides a clean interface for all development tasks:

make help              # Show all available targets
make update            # Initialize and update git submodules
make install           # Install dependencies
make dev               # Start development server
make build             # Build the project
make test              # Run tests
make lint              # Run linter
make format            # Format code
make check             # Run all checks
make clean             # Clean build artifacts
make shell             # Enter Nix development shell

Every command automatically runs within the Nix environment, ensuring consistency across different machines and operating systems.

Git Submodules: The Right Way

Working with git submodules can be tricky, but we've established best practices:

Common Pitfalls and Solutions

Problem: git status shows submodule changes after installing dependencies.

Solution: Dependencies like node_modules/ are properly ignored in the submodule's .gitignore. However, some files may have permission changes during installation (like executable scripts). To handle this:

# Check what changed
cd src && git status

# Discard unintended changes
git submodule foreach git checkout -- .

# Reset submodule to clean state
git submodule update --init --recursive

Key Principle: Treat submodules as read-only for local changes. If you need to modify Strudel itself, commit changes to the upstream repository first.

AI-Assisted Development: Guidelines for Success

Our AGENTS.md document provides comprehensive guidelines for AI assistants working with Strudel. Here are the critical points:

Strudel is NOT JavaScript

Despite being built with JavaScript, Strudel uses its own pattern-based syntax:

// ✅ CORRECT - Direct pattern composition
$: sound("bd*4")
$: sound("~ sd ~ sd")
$: sound("hh*8").gain(0.3)

// ❌ WRONG - JavaScript-style approach
const kick = sound("bd*4");
const snare = sound("~ sd ~ sd");

Essential Syntax Patterns

Parallel Patterns: Use multiple $: lines for simultaneous playback Muting: Prefix with _ to silence patterns during live performance Mini-notation: "bd ~ sd ~" for rhythmic patterns Scale-based Composition: Use n("0 2 4 6").scale("C:minor") instead of manual note names

Sound Sources and Effects

// Drum samples
$: sound("bd sd hh oh")

// Synthesizers with scales
$: n("0 2 4 6").scale("C:minor").sound("sawtooth")

// Live effects
$: sound("bd*4").lpf(sine.range(200, 2000).slow(8))

Live Performance Best Practices

Each $: line is independently controllable
Use _$: to mute sections during performance
Include modulation for evolving sounds
Keep patterns readable for live modification

Nix Flake Configuration Deep Dive

Our flake.nix provides a robust development environment:

{
  description = "Strudel development environment";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
      in
      {
        devShells.default = pkgs.mkShell {
          buildInputs = with pkgs; [
            nodejs_20
            pnpm
            git
          ];

          shellHook = ''
            echo "Strudel development environment loaded"
            echo "Node.js: $(node --version)"
            echo "pnpm: $(pnpm --version)"
          '';
        };
      });
}

This configuration:

Pins Nixpkgs to version 25.05 for reproducibility
Provides Node.js 20 and pnpm for package management
Includes git for version control operations
Shows version information on shell entry

Contributing and Best Practices

When contributing to Strudel development:

Follow the guidelines in AGENTS.md for AI-assisted work
Use lowercase commit messages
Ensure all changes pass make check
Test thoroughly before submitting

Troubleshooting Common Issues

Submodule Problems

make update  # Reinitialize submodules

Dependency Issues

make clean && make install  # Fresh dependency installation

Nix Issues

Ensure Nix is installed and up-to-date. On Linux:

sh <(curl -L https://nixos.org/nix/install) --daemon

The Power of Reproducible Environments

This Nix-based setup eliminates common development headaches:

Zero configuration drift: Everyone gets identical environments
Easy onboarding: New contributors can start coding immediately
Version pinning: Dependencies are locked to specific versions
Cross-platform compatibility: Works on Linux, macOS, and Windows (via WSL)

Live Coding with Strudel: A Glimpse

Once set up, you can start creating algorithmic music immediately:

// Basic beat
$: sound("bd*4").gain(0.8)
$: sound("~ sd ~ sd").gain(0.7)
$: sound("hh*8").gain(0.3)

// Melodic elements
$: n("0 ~ 2 ~ 4 ~ 6 ~").scale("C2:minor").sound("sawtooth").lpf(1200)
$: n("~ 0 ~ 2 ~ 4 ~ 6").scale("C4:minor").sound("piano").room(0.6)

// Live effects
_$: sound("bd*4").lpf(sine.range(200, 2000).slow(8))  // muted filter sweep

Conclusion

Setting up a proper development environment for Strudel isn't just about getting code to run—it's about creating a sustainable, collaborative workflow that scales. Our Nix-based approach, combined with careful submodule management and comprehensive guidelines, provides a solid foundation for both individual exploration and team development.

Whether you're a seasoned live coder or just starting your algorithmic music journey, this environment ensures you can focus on what matters most: creating amazing sounds.

The Strudel community welcomes contributors at all levels. Check out the official Strudel website and workshop to learn more, and join us in pushing the boundaries of live coding music!

This post is part of our series on reproducible development environments. Stay tuned for more insights into modern software development practices.

8.9 KiB Raw Blame History