CONTRIBUTION.md

Contributing to next-yak

Thank you for your interest in contributing to next-yak! This document provides guidelines and instructions for contributing to the project.

Table of contents

• Development setup
  • Prerequisites
  • Initial setup
  • Project structure
• Developping next-yak TypeScript/JavaScript
• Developing yak-swc Rust
  • Running the example app
• Submitting a pull request
• Common issues
  • Rust setup issues
  • Build issues
  • Test issues

Development setup

Prerequisites

Before you begin

• Install Node.js v20.x or later
• Install pnpm v8.6.1 or later
• Install Rust toolchain
  ⚠️ Important
  Do not use brew or other package managers to install Rust, as this can lead to permission issues
  Install Rust from rust-lang.org, following the official instructions for your platform
• Add the Rust WebAssembly target, execute

  rustup target add wasm32-wasi

Initial setup

Clone the repository

git clone https://github.com/jantimon/next-yak.git
cd next-yak

Install dependencies

pnpm install

Build everything (required before running examples or tests)

pnpm run build
pnpm run build:swc

Project structure

The monorepo is organized into several key packages and directories:

The main package

• next-yak - TypeScript/JavaScript code for Next.js

Rust packages under ./packages/yak-swc/:

• yak-swc - SWC plugin, npm package, and Rust library
• ./yak_swc - Core SWC plugin implementation in Rust
• ./css_in_js_parser - Rust library for parsing CSS-in-JS syntax
• ./relative_posix_path - Rust utility for path handling

Additional packages

• benchmark - CI-benchmarking tool
• example - Demo Next.js application, featuring various use cases
• docs - Documentation and playground, hosted at yak.js.org

Developping next-yak TypeScript/JavaScript

The main package is written in TypeScript. The package is responsible for transforming components and serving styles to the module CSS system of Next.js. The TypeScript/JavaScript code is located in the ./packages/next-yak directory.

Building, from the the ./ or the ./packages/next-yak directory:

pnpm build

Running the tests

pnpm test

Test watch mode

pnpm test:watch

Updating test snapshots

pnpm test:snapshots

Developing yak-swc Rust

The SWC plugin is written in Rust and compiled to WebAssembly. The plugin is responsible for transforming TypeScript and extracting CSS-in-JS styles from components. The Rust code is located in the ./packages/yak-swc directory, it's recommended to open the IDE in this directory to work on the SWC plugin. Opening the IDE in the ./packages/yak-swc directory will allow the Rust toolchain to work correctly.

Running the scripts from the ./packages/yak-swc directory:

Build the SWC plugin

pnpm build

Tests for the SWC plugin

pnpm test

For updating test snapshots in the SWC plugin

pnpm test:snapshots

Running the example app

The example app is a Next.js application that demonstrates the features of next-yak. The example app is located in the ./packages/example directory.

Build everything and start the example app

pnpm build
pnpm build:swc
pnpm example

Debugging the SWC plugin in the example app, you can enable debug logging

// ./packages/example/next.config.mjs
export default withYak({
  experiments: {
    debug: true, // or { filter: (path) => path.includes('component.tsx'), type: 'css' }
  },
});

Submitting a pull request

1. Fork the repository

2. Create a new feature branch:

   git checkout -b feature/your-feature-name

3. Make your changes, following these guidelines:

   • Write tests for new features
   • Follow existing code style
   • Keep commits focused and atomic
   • Write clear commit messages

4. Run tests to ensure everything works

5. Create a changlog entry

   This step is mandatory, if there is no change to the public API, you may want to add an empty changeset by adding the --empty flag.

   pnpm changeset

6. Push changes and create a pull request

Common issues

Rust setup issues

• Permission problems with Rust: Make sure to install Rust from rust-lang.org and not through package managers
• Missing wasm32-wasi target: Run rustup target add wasm32-wasi
• Cargo build failures: Ensure you have the latest stable Rust toolchain with rustup update stable

Build issues

• SWC plugin not found: Make sure to run pnpm build:swc before starting the example app
• Missing dependencies: Run pnpm install and ensure all peer dependencies are satisfied

Test issues

• Snapshot test failures: Use pnpm test:snapshots to update all snapshots, swc and JavaScript

---

For any questions not covered here, please feel free to open an issue.