diff --git a/POST.md b/POST.md new file mode 100644 index 0000000..83c8ac2 --- /dev/null +++ b/POST.md @@ -0,0 +1,277 @@ +--- +title: "Mastering Strudel: A Reproducible Development Environment with Nix" +date: 2025-09-27T12:00:00+02:00 +draft: false +tags: ["strudel", "nix", "development", "live-coding"] +categories: ["Development"] +build: + render: never +list: never +publishResources: false +--- + +# 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](https://nixos.org/download.html) package manager (version 2.4+) +- Git for version control + +### Step-by-Step Setup + +1. **Clone the repository**: + ```bash + git clone + cd strudel + ``` + +2. **Initialize git submodules**: + ```bash + make submodules-init submodules-update + ``` + This pulls in the official Strudel codebase as a submodule in the `src/` directory. + +3. **Enter the development environment**: + ```bash + make shell + ``` + This launches a Nix shell with Node.js 20, pnpm, and git pre-configured. + +4. **Install dependencies**: + ```bash + make install + ``` + This runs `pnpm install` within the Nix environment, ensuring consistent package versions. + +5. **Start the development server**: + ```bash + 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: + +```bash +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: + +```bash +# 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: + +```javascript +// ✅ 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 + +```javascript +// 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: + +```nix +{ + 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 +```bash +make update # Reinitialize submodules +``` + +### Dependency Issues +```bash +make clean && make install # Fresh dependency installation +``` + +### Nix Issues +Ensure Nix is installed and up-to-date. On Linux: +```bash +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: + +```javascript +// 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](https://strudel.cc/) and [workshop](https://strudel.cc/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.* \ No newline at end of file