From b5f0fd8e514431164600b2af7117d5ac37c4ea14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matthias=20J=C3=A4ggli?= Date: Fri, 8 Nov 2024 14:41:10 +0100 Subject: [PATCH] Refactor docs --- contributing-guide.md | 119 ++++++++++++------------------- package.json | 13 ++-- packages/example/next.config.mjs | 16 +++-- 3 files changed, 62 insertions(+), 86 deletions(-) diff --git a/contributing-guide.md b/contributing-guide.md index 67c19093..3c452931 100644 --- a/contributing-guide.md +++ b/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
+ **⚠️ 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](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,117 +50,98 @@ 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' } @@ -170,16 +149,10 @@ export default withYak({ }); ``` -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 ``` diff --git a/package.json b/package.json index 4f837583..72d3eb9b 100644 --- a/package.json +++ b/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": { diff --git a/packages/example/next.config.mjs b/packages/example/next.config.mjs index 29ab8923..3d8ea0bc 100644 --- a/packages/example/next.config.mjs +++ b/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);