Refactor docs

contributing-guide.md

@@ -21,17 +21,15 @@ Thank you for your interest in contributing to next-yak! This document provides
 
 ### Prerequisites
 
-Before you begin, make sure you have the following installed
-
-1. Node.js (v20 or later)
-2. pnpm (v8.6.1 or later)
-3. Rust toolchain - **Important**: Install from [rust-lang.org](https://www.rust-lang.org/tools/install)
-   - ⚠️ Do not use brew or other package managers to install Rust, as this can lead to permission issues
-   - Follow the official installation instructions for your platform
-4. Rust WebAssembly target:
-   ```bash
-   rustup target add wasm32-wasi
-   ```
+Before you begin
+
+- Install [Node.js](https://nodejs.org/en) v20.x or later
+- Install [pnpm](https://pnpm.io/) v8.6.1 or later
+- Install [Rust](https://www.rust-lang.org/) toolchain <br />
+  **⚠️ Important**<br />
+  Do _not_ use brew or other package managers to install Rust, as this can lead to permission issues<br />
+  Install Rust from [rust-lang.org](https://www.rust-lang.org/tools/install), following the official instructions for your platform
+- Execute `rustup target add wasm32-wasi` to add the Rust WebAssembly target
 
 ### Initial setup
 
@@ -52,134 +50,109 @@ Build everything (required before running examples or tests)
 
 ```bash
 pnpm run build
+pnpm run build:swc
 ```
 
-### Project Structure
+### Project structure
 
-The repository is organized into several key directories, using a monorepo structure:
+The monorepo is organized into several key packages and directories:
 
-The packages under `./packages/`:
+The main package
 
-- [benchmark](./packages/benchmark) - CI-benchmarking tool
-- [example](./packages/example) - Demo Next.js application, featuring various use cases
-- [docs](./packages/docs) - Documentation and playground, hosted at [yak.js.org](https://yak.js.org/)
-- [next-yak](./packages/next-yak) - Main NPM package with TypeScript/JavaScript code
-- [yak-swc](./packages/yak-swc) - SWC plugin
+- [next-yak](./packages/next-yak) - TypeScript/JavaScript code for Next.js
 
 Rust packages under `./packages/yak-swc/`:
 
+- [yak-swc](./packages/yak-swc) - SWC plugin, npm package, and Rust library
 - [./yak_swc](./packages/yak-swc/yak_swc) - Core SWC plugin implementation in Rust
 - [./css_in_js_parser](./packages/yak-swc/css_in_js_parser) - Rust library for parsing CSS-in-JS syntax
 - [./relative_posix_path](./packages/yak-swc/relative_posix_path) - Rust utility for path handling
 
-## Development Workflow
-
-### Running Tests
+Additional packages
 
-The project includes tests for both JavaScript and Rust components:
+- [benchmark](./packages/benchmark) - CI-benchmarking tool
+- [example](./packages/example) - Demo Next.js application, featuring various use cases
+- [docs](./packages/docs) - Documentation and playground, hosted at [yak.js.org](https://yak.js.org/)
 
-Run all tests:
+## Developping `next-yak` TypeScript/JavaScript
 
-```bash
-pnpm test
-```
+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.
 
-Run all `next-yak` tests:
+Building, from the the `./` or the `./packages/next-yak` directory:
 
 ```bash
-pnpm test:next-yak
+pnpm run build
 ```
 
-Run `yak-swc` tests:
+Running the tests
 
 ```bash
-pnpm test:yak-swc
+pnpm test
 ```
 
-Watch mode for `next-yak` tests:
+Test watch mode
 
 ```bash
-pnpm test:next-yak:watch
+pnpm test:watch
 ```
 
-### Updating Test Snapshots
-
-Update all snapshots
+Updating test snapshots
 
 ```bash
 pnpm test:snapshots
 ```
 
-For updating test snapshots in the `next-yak` package:
+## Developing `yak-swc` Rust
 
-```bash
-pnpm test:snapshots:next-yak
-```
+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.
 
-For updating test snapshots in the SWC plugin:
+Running the scripts from the `./packages/yak-swc` directory:
 
-```bash
-pnpm test:snapshots:yak-swc
-```
-
-### Running the Example App
-
-Build everything and start the example app
+Build the SWC plugin
 
 ```bash
 pnpm run build
-pnpm example
 ```
 
-## Building
-
-Build everything
+Tests for the SWC plugin
 
 ```bash
-pnpm run build
+pnpm test
 ```
 
-Build only `next-yak`
+For updating test snapshots in the SWC plugin
 
 ```bash
-pnpm run build:next-yak
+pnpm test:snapshots
 ```
 
-Build only the SWC plugin
+### Running the example app
 
-```bash
-pnpm run build:swc
-```
+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.
 
-Watch mode during development
+Build everything and start the example app
 
 ```bash
-pnpm run watch
+pnpm run build && pnpm run build:swc
+pnpm example
 ```
 
-## Debugging
-
-When debugging the SWC plugin, you can enable debug logging:
+Debugging the SWC plugin in the example app, you can enable debug logging
 
 ```js
-// next.config.js
+// ./packages/example/next.config.mjs
 export default withYak({
   experiments: {
     debug: true, // or { filter: (path) => path.includes('component.tsx'), type: 'css' }
   },
 });
 ```
 
-Debug types:
-
-- `'ts'` - Show transformed TypeScript
-- `'css'` - Show extracted CSS
-- `'css resolved'` - Show CSS after resolving imports
-
-## Making Contributions
+## Contribution steps
 
 1. Fork the repository
-2. Create a new branch:
+2. Create a new feature branch:
    ```bash
    git checkout -b feature/your-feature-name
    ```

package.json

@@ -7,19 +7,14 @@
     "packages/*"
   ],
   "scripts": {
-    "build:next-yak": "pnpm run --filter=next-yak build",
+    "build": "pnpm run --filter=next-yak build",
     "build:swc": "pnpm run --filter=yak-swc build",
-    "build": "pnpm run build:next-yak && pnpm run build:swc",
     "example": "pnpm --filter=next-yak-example run dev",
     "package:types": "npx --package=@arethetypeswrong/cli attw --pack packages/next-yak",
     "prettier": "pnpm run --recursive --if-present prettier",
-    "test": "pnpm run test:next-yak && pnpm run test:swc",
-    "test:snapshots": "pnpm run test:next-yak:snapshots && pnpm run test:swc:snapshots",
-    "test:next-yak": "pnpm run build:next-yak && pnpm --filter=next-yak --filter=cross-file-tests --filter=next-yak-example run \"/test($|:types)/\"",
-    "test:next-yak:watch": "pnpm --filter=next-yak run test:watch",
-    "test:next-yak:snapshots": "pnpm --filter=next-yak run test:snapshots",
-    "test:swc": "pnpm --filter=yak-swc run test",
-    "test:swc:snapshots": "pnpm --filter=yak-swc run test:snapshots",
+    "test": "pnpm run build:next-yak && pnpm --filter=next-yak --filter=cross-file-tests --filter=next-yak-example run \"/test($|:types)/\"",
+    "test:watch": "pnpm --filter=next-yak run test:watch",
+    "test:snapshots": "pnpm --filter=next-yak run test:snapshots",
     "watch": "pnpm run --filter=next-yak watch"
   },
   "engines": {

packages/example/next.config.mjs

@@ -1,8 +1,16 @@
-import { withYak } from 'next-yak/withYak';
+import { withYak } from "next-yak/withYak";
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {
+  /**
+   * Debug types:
+   * - `'ts'` - Show transformed TypeScript
+   * - `'css'` - Show extracted CSS
+   * `'css resolved'` - Show CSS after resolving imports
+   */
+  // experiments: {
+  //   debug: { filter: (path) => path.includes('component.tsx'), type: 'css' }
+  // },
+};
 
-}
-
-export default withYak(nextConfig)
+export default withYak(nextConfig);