chore: bump version to v0.17.7 (#523)

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

.editorconfig

@@ -0,0 +1,7 @@
+[*]
+charset = utf-8
+insert_final_newline = true
+end_of_line = lf
+indent_style = space
+indent_size = 2
+max_line_length = 80

.eslintrc

@@ -1,103 +0,0 @@
-{
-  "root": true,
-  "reportUnusedDisableDirectives": true,
-  "ignorePatterns": ["**/build", "**/dist"],
-  "parser": "@typescript-eslint/parser",
-  "plugins": ["@typescript-eslint", "import"],
-  "extends": [
-    "eslint:recommended",
-    "plugin:@typescript-eslint/recommended",
-    "plugin:@typescript-eslint/stylistic",
-    "plugin:import/recommended",
-    "plugin:import/typescript",
-    "prettier",
-  ],
-  "env": {
-    "browser": true,
-    "es2020": true,
-  },
-  "parserOptions": {
-    "tsconfigRootDir": ".",
-    "project": true,
-    "sourceType": "module",
-    "ecmaVersion": 2020,
-  },
-  "settings": {
-    "import/parsers": {
-      "@typescript-eslint/parser": [".ts", ".tsx"],
-    },
-    "import/resolver": {
-      "typescript": true,
-    },
-    "react": {
-      "version": "detect",
-    },
-  },
-  "rules": {
-    "@typescript-eslint/array-type": "error",
-    "@typescript-eslint/ban-types": "error",
-    "@typescript-eslint/ban-ts-comment": "error",
-    "@typescript-eslint/consistent-type-definitions": "error",
-    "@typescript-eslint/consistent-type-imports": [
-      "error",
-      { "prefer": "type-imports" },
-    ],
-    "@typescript-eslint/explicit-module-boundary-types": "error",
-    "@typescript-eslint/method-signature-style": ["error", "property"],
-    "@typescript-eslint/naming-convention": [
-      "error",
-      {
-		"selector": "typeParameter",
-        "format": ["PascalCase"],
-        "leadingUnderscore": "forbid",
-        "trailingUnderscore": "forbid",
-        "custom": {
-          "regex": "^(T|T[A-Z][A-Za-z]+)$",
-          "match": true,
-        },
-      },
-    ],
-    "@typescript-eslint/no-empty-function": "error",
-    "@typescript-eslint/no-empty-interface": "error",
-    "@typescript-eslint/no-explicit-any": "off",
-    "@typescript-eslint/no-non-null-assertion": "error",
-    "@typescript-eslint/no-unnecessary-condition": "error",
-    "@typescript-eslint/no-unnecessary-type-assertion": "error",
-    "@typescript-eslint/no-unused-vars": "error",
-    "@typescript-eslint/explicit-function-return-type": "error",
-    "@typescript-eslint/no-inferrable-types": [
-      "error",
-      { "ignoreParameters": true },
-    ],
-    "import/default": "error",
-    "import/export": "error",
-    "import/namespace": "error",
-    "import/newline-after-import": "error",
-    "import/no-cycle": "error",
-    "import/no-duplicates": "off",
-    "import/no-named-as-default-member": "error",
-    "import/no-unused-modules": "error",
-    "import/order": [
-      "off",
-      {
-        "groups": [
-          "builtin",
-          "external",
-          "internal",
-          "parent",
-          "sibling",
-          "index",
-          "object",
-          "type",
-        ],
-      },
-    ],
-    "no-case-declarations": "error",
-    "no-empty": "error",
-    "no-prototype-builtins": "error",
-    "no-redeclare": "error",
-    "no-shadow": "error",
-    "no-undef": "off",
-    "sort-imports": "off",
-  },
-}

.gitattributes

@@ -1 +1,10 @@
 examples/** linguist-documentation
+*.css linguist-detectable=false
+*.scss linguist-detectable=false
+*.js linguist-detectable=false
+*.jsx linguist-detectable=true
+*.tsx linguist-detectable=true
+*.ts linguist-detectable=true
+*.rs linguist-detectable=true 
+*.html linguist-detectable=false  
+*.sh linguist-detectable=false

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,60 @@
+name: Bug report
+description: File a bug report
+title: '[Bug]: '
+type: Bug
+labels: ['bug']
+
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+  - type: textarea
+    id: expected-behaviour
+    attributes:
+      label: Expected behaviour
+      description: A clear and concise description of what you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: How to reproduce
+      description: Steps to reproduce the behavior (code, example repository)
+    validations:
+      required: true
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots
+      description: If applicable, add screenshots to help explain your problem.
+    validations:
+      required: false
+  - type: textarea
+    id: system-info
+    attributes:
+      label: System Info
+      description: Output of `npx envinfo --system --npmPackages 'tuono' --binaries --browsers`
+      render: shell
+      placeholder: System, Binaries, Browsers
+    validations:
+      required: true
+  - type: textarea
+    id: system-info-rust
+    attributes:
+      label: System info (Rust)
+      description: Output of `rustc --version && cargo --version && tuono --version`
+      render: shell
+      placeholder: 'rustc, cargo and tuono binary version'
+    validations:
+      required: true
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional context
+      description: Add any other context about the bug here.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Ask a question / Get support
+    url: https://discord.com/invite/khQzPa654B
+    about: Ask questions and discuss with other community members

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,36 @@
+name: Feature request
+description: Suggest an idea for this project
+title: '[Feature request]: '
+type: Feature
+labels: ['enhancement']
+
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Is your feature request related to a problem? Please describe.
+      description: A clear and concise description of what the problem is.
+      placeholder: I'm always frustrated when [...]
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Describe the solution you'd like
+      description: A clear and concise description of what you want to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Describe alternatives you've considered
+      description: A clear and concise description of any alternative solutions or features you've considered.
+    validations:
+      required: false
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional context
+      description: Add any other context or screenshots about the feature request here.
+    validations:
+      required: false

.github/actions/install-node-dependencies/action.yml

@@ -0,0 +1,37 @@
+name: Install NodeJS Dependencies
+description: This is a composite GitHub Action that sets up pnpm, node and installs the project's dependencies.
+
+inputs:
+  node-version:
+    description: 'Explicit node version. Otherwise fallback reading `.nvmrc`. Use in conjunction with matrix'
+    required: false
+  registry-url:
+    description: 'https://github.com/actions/setup-node?tab=readme-ov-file#usage'
+    required: false
+    default: ''
+
+runs:
+  using: composite
+  steps:
+    - name: Install pnpm
+      uses: pnpm/action-setup@v4
+
+    - name: Setup Node.js (via input)
+      if: ${{ inputs.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+        registry-url: ${{ inputs.registry-url }}
+        cache: 'pnpm'
+
+    - name: Setup Node.js (via .nvmrc)
+      if: ${{ !inputs.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version-file: '.nvmrc'
+        registry-url: ${{ inputs.registry-url }}
+        cache: 'pnpm'
+
+    - name: Install Dependencies
+      shell: bash
+      run: pnpm install --frozen-lockfile

.github/labeler.yml

@@ -0,0 +1,36 @@
+# @see https://github.com/actions/labeler
+
+rust:
+  - changed-files:
+      - any-glob-to-any-file: ['crates/**', 'Cargo.toml']
+
+typescript:
+  - changed-files:
+      - any-glob-to-any-file:
+          [
+            'packages/**',
+            'package.json',
+            'pnpm-*.yaml',
+            'eslint.config.js',
+            'tsconfig.json',
+          ]
+
+documentation:
+  - changed-files:
+      - any-glob-to-any-file: ['apps/documentation/**']
+
+'CI/CD':
+  - changed-files:
+      - any-glob-to-any-file: ['.github/**']
+
+'repo maintenance':
+  - changed-files:
+      - any-glob-to-any-file:
+          [
+            '.npmrc',
+            '.nvmrc',
+            '.prettierrc',
+            '.prettierignore',
+            'renovate.json',
+            'turbo.json',
+          ]

.github/pull_request_template.md

@@ -0,0 +1,24 @@
+<!--
+👋 Thank you for your Pull Request 🙏
+-->
+
+### Checklist
+
+- [ ] I have read [Contributing > Pull requests](https://tuono.dev/documentation/contributing/pull-requests)
+
+### Related issue
+
+Fixes #0
+
+<!-- Replace the content with "None" if you haven't an issue to link -->
+
+### Overview
+
+<!--
+
+Explain the context and why you're making that change.
+What is the problem you're trying to solve?
+If a new feature is being added,
+describe the intended use case that feature fulfills.
+
+-->

.github/workflows/docker-ci.yml

@@ -0,0 +1,61 @@
+name: Docker CI
+
+# If we need support more OS refer to
+# https://github.com/tuono-labs/tuono/pull/332#issuecomment-2614439692
+
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request:
+
+concurrency:
+  group: '${{ github.workflow }}-${{ github.head_ref || github.ref }}'
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build_and_test:
+    name: Build and Test Docker Image on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build and Run Docker Compose
+        run: |
+          docker compose -f docker/compose.yml up --build -d
+
+      - name: Check if the container is running
+        run: |
+          docker ps --filter "name=tuono-source-container" --format "table {{.Names}}\t{{.Status}}"
+          if ! docker ps --filter "name=tuono-source-container" --format "{{.Status}}" | grep -q "Up"; then
+            echo "Error: Container 'tuono-source-container' is not running."
+            exit 1
+          fi
+
+      - name: Check commands inside container
+        run: |
+          docker exec tuono-source-container pnpm --version || { echo "Error: pnpm is not available."; exit 1; }
+          docker exec tuono-source-container tuono --version || { echo "Error: tuono is not available."; exit 1; }
+
+      - name: Run cargo test
+        run: docker exec tuono-source-container cargo test
+
+      - name: Install node dependencies in each tuono's sub-projets
+        run: docker exec tuono-source-container bash -c 'for dir in /tuono/packages/*; do [ -d "$dir" ] && (cd "$dir" && yes | pnpm install --frozen-lockfile); done'
+
+      - name: Run pnpm test
+        run: docker exec tuono-source-container pnpm test
+
+      - name: Tear Down Docker Compose
+        if: always()
+        run: |
+          docker compose -f docker/compose.yml down --volumes

.github/workflows/documentation-ci.yml

@@ -0,0 +1,77 @@
+name: Documentation Website CI
+
+on:
+  push:
+    branches:
+      - 'main'
+    # match
+    # - all files inside `apps/documentation` and `.github`
+    # - all files in the root expect `Cargo.toml`
+    paths:
+      - '.github/**'
+      - '*'
+      - '!Cargo.toml'
+      - 'apps/documentation/**'
+  pull_request:
+    # same as `on.push.paths`
+    paths:
+      - '.github/**'
+      - '*'
+      - '!Cargo.toml'
+      - 'apps/documentation/**'
+
+concurrency:
+  group: '${{ github.workflow }}-${{ github.head_ref || github.ref }}'
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    name: Check build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install NodeJS Dependencies
+        uses: ./.github/actions/install-node-dependencies
+
+      - name: Setup rust
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+
+      # ⬇️ Keep in sync with `.github/workflows/deploy-documentation.yml`
+      - name: Read tuono version used by the documentation
+        id: get_tuono_version
+        run: |
+          VERSION=$(pnpm ls tuono --filter=documentation | grep "tuono " | sed -E 's/.* ([0-9]+\.[0-9]+\.[0-9]+).*/\1/')
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Install tuono
+        run: cargo install tuono@${{ steps.get_tuono_version.outputs.version }}
+      # ⬆️
+
+      - name: Build project
+        working-directory: ./apps/documentation
+        run: tuono build --static
+
+  code_check:
+    name: Check format, lint and types
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install NodeJS Dependencies
+        uses: ./.github/actions/install-node-dependencies
+
+      - name: Check formatting
+        run: pnpm docs:format:check
+
+      - name: Lint
+        run: pnpm docs:lint
+
+      - name: Types
+        run: pnpm docs:types

.github/workflows/documentation-deploy.yml

@@ -0,0 +1,55 @@
+name: Documentation Website Deploy on AWS S3
+
+on:
+  push:
+    branches:
+      - 'main'
+    paths:
+      - '.github/**'
+      - 'apps/documentation/**'
+
+jobs:
+  deploy-documentation:
+    name: Deploy
+    runs-on: ubuntu-latest
+
+    env:
+      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install NodeJS Dependencies
+        uses: ./.github/actions/install-node-dependencies
+
+      - name: Setup rust
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+
+      # ⬇️ Keep in sync with `.github/workflows/ci-documentation.yml`
+      - name: Read tuono version used by the documentation
+        id: get_tuono_version
+        run: |
+          VERSION=$(pnpm ls tuono --filter=documentation | grep "tuono " | sed -E 's/.* ([0-9]+\.[0-9]+\.[0-9]+).*/\1/')
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Install tuono
+        run: cargo install tuono@${{ steps.get_tuono_version.outputs.version }}
+      # ⬆️
+
+      - name: Build project
+        working-directory: ./apps/documentation
+        run: tuono build --static
+
+      - name: Deploy
+        uses: reggionick/s3-deploy@v4
+        with:
+          folder: apps/documentation/out/static
+          bucket: tuono-documentation
+          bucket-region: eu-west-3
+          dist-id: ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }}
+          invalidation: /
+          delete-removed: true
+          no-cache: true
+          private: true
+          files-to-include: '{.*/**,**}'

.github/workflows/pr-labeler.yml

@@ -0,0 +1,27 @@
+name: 'PR Labeler'
+
+# @see https://github.com/actions/labeler
+# @see .github/labeler.yml
+
+on:
+  - pull_request_target
+
+jobs:
+  labeler:
+    name: 'Manage labels'
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      # Add checkout step to load labeler.yml locally,
+      # rather than from an API request
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - uses: actions/labeler@v5
+        with:
+          sync-labels: true

.github/workflows/pr-title-checker.yml

@@ -0,0 +1,61 @@
+name: 'PR Title Checker'
+
+# This workflow ensures that PR titles adhere to a pattern
+# similar to conventional commits standard
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+      - labeled
+      - unlabeled
+
+env:
+  PR_TITLE: ${{ github.event.pull_request.title }}
+
+jobs:
+  check_pr_title:
+    name: 'PR Title Checker'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check type
+        id: type
+        # @warning Keep in sync with apps/documentation/src/routes/documentation/contributing/pull-requests.mdx
+        run: |
+          VALID_COMMIT_TYPES="chore|ci|docs|feat|fix|refactor|test"
+          REGEX="^(${VALID_COMMIT_TYPES})(\(.*\))?!?: .*"
+
+          if ! [[ $PR_TITLE =~ $REGEX ]]; then
+            echo "::error title=Type::The title has an incorrect type. Valid types are ${VALID_COMMIT_TYPES}"
+            echo "result=fail" >> "$GITHUB_OUTPUT"
+          else
+            echo "::notice title=Type::The title is using a valid type"
+            echo "result=ok" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Check length
+        id: length
+        run: |
+          MAX_LENGTH=100
+          LENGTH=${#PR_TITLE}
+
+          if [ $LENGTH -gt $MAX_LENGTH ]; then
+            echo "::error title=Length::The title is longer than $MAX_LENGTH characters"
+            echo "result=fail" >> "$GITHUB_OUTPUT"
+          else
+            echo "::notice title=Length::The title length is within the maximum value of $MAX_LENGTH characters"
+            echo "result=ok" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Check result
+        env:
+          FAILURE: ${{ contains(join(steps.*.outputs.result, ','), 'fail') }}
+        run: |
+          echo "Failure: $FAILURE"
+          if [ "$FAILURE" = "false" ]; then
+            exit 0
+          else
+            exit 1
+          fi

.github/workflows/release.yml

@@ -1,78 +1,68 @@
 name: Publish on npm and crates
+
 on:
   release:
     types: [published]
 
 jobs:
-  publish-on-npm-dry-run:
+  publish_npm_dry_run:
+    name: NPM publish (dry run)
     runs-on: ubuntu-latest
+
     steps:
-      - name: Checkout
+      - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Install Node.js
-        uses: actions/setup-node@v4
+      - name: Install NodeJS Dependencies
+        uses: ./.github/actions/install-node-dependencies
         with:
-          node-version: 20
           registry-url: 'https://registry.npmjs.org'
 
-      - uses: pnpm/action-setup@v3
-        name: Install pnpm
-        with:
-          version: 8
-          run_install: false
-
-      - name: Install dependencies
-        run: pnpm install 
-
       - name: Build
         run: pnpm build
 
       - name: Publish
-        run: pnpm publish -r --no-git-checks --dry-run 
+        run: pnpm publish -r --no-git-checks --dry-run
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-  publish-on-crates-dry-run:
+  publish_crates_dry_run:
+    name: Crates publish (dry run)
     runs-on: ubuntu-latest
+
     steps:
-    - uses: actions/checkout@v3
-    - uses: actions-rs/toolchain@v1
-      with:
-          toolchain: stable
-          override: true
-    - uses: katyo/publish-crates@v2
-      with:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: 'stable'
+
+      - uses: katyo/publish-crates@v2
+        with:
           path: './crates/tuono'
           dry-run: true
           registry-token: ${{ secrets.CARGO_REGISTRY_TOKEN }}
           check-repo: true
 
-  publish-on-npm:
-    needs: [publish-on-crates-dry-run, publish-on-npm-dry-run]
+  publish_npm:
+    name: NPM publish
+    needs: [publish_npm_dry_run, publish_crates_dry_run]
     runs-on: ubuntu-latest
+
     steps:
-      - name: Checkout
+      - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Install Node.js
-        uses: actions/setup-node@v4
+      - name: Install NodeJS Dependencies
+        uses: ./.github/actions/install-node-dependencies
         with:
-          node-version: 20
           registry-url: 'https://registry.npmjs.org'
 
-      - uses: pnpm/action-setup@v3
-        name: Install pnpm
-        with:
-          version: 8
-          run_install: false
-
       - name: Clone root README.md on tuono package
         run: cp README.md packages/tuono/README.md
 
-      - name: Install dependencies
-        run: pnpm install 
-
       - name: Build
         run: pnpm build
 
@@ -81,17 +71,22 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-  publish-on-crates:
-    needs: [publish-on-crates-dry-run, publish-on-npm-dry-run]
+  publish_crates:
+    name: Crates publish
+    needs: [publish_npm_dry_run, publish_crates_dry_run]
     runs-on: ubuntu-latest
+
     steps:
-    - uses: actions/checkout@v3
-    - uses: actions-rs/toolchain@v1
-      with:
-          toolchain: stable
-          override: true
-    - uses: katyo/publish-crates@v2
-      with:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: 'stable'
+
+      - uses: katyo/publish-crates@v2
+        with:
           path: './crates/tuono'
           registry-token: ${{ secrets.CARGO_REGISTRY_TOKEN }}
           check-repo: true

.github/workflows/repo-root-ci.yml

@@ -0,0 +1,51 @@
+name: Repo root CI
+
+# All workflows are triggered based on specific paths,
+# the root repository is something that is not applicable to rust nor typescript
+# so it has been moved in a standalone workflow
+
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request:
+
+concurrency:
+  group: '${{ github.workflow }}-${{ github.head_ref || github.ref }}'
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  format:
+    name: Check format
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install NodeJS Dependencies
+        uses: ./.github/actions/install-node-dependencies
+
+      - name: Test project
+        run: pnpm repo:root:format:check
+
+  ci_ok:
+    name: Repo root CI OK
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    if: always()
+    needs: [format]
+    env:
+      FAILURE: ${{ contains(join(needs.*.result, ','), 'failure') }}
+      CANCELLED: ${{ contains(join(needs.*.result, ','), 'cancelled') }}
+    steps:
+      - name: Check for failure or cancelled jobs result
+        shell: bash
+        run: |
+          echo "Failure: $FAILURE - Cancelled: $CANCELLED"
+          if [ "$FAILURE" = "false" ] && [ "$CANCELLED" = "false" ]; then
+            exit 0
+          else
+            exit 1
+          fi

.github/workflows/rust-ci.yml

@@ -0,0 +1,86 @@
+name: Rust CI
+
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request:
+
+concurrency:
+  group: '${{ github.workflow }}-${{ github.head_ref || github.ref }}'
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build_and_test:
+    name: Build and test crates on ${{ matrix.os }} with rust ${{ matrix.toolchain }}
+
+    strategy:
+      fail-fast: true
+      matrix:
+        os:
+          - 'ubuntu-latest'
+          - 'macos-latest'
+          - 'windows-latest'
+        toolchain:
+          - 'stable'
+
+        # Test `beta` and `nightly` toolchains only on `ubuntu`
+        # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow#expanding-or-adding-matrix-configurations
+        include:
+          - toolchain: 'beta'
+            os: 'ubuntu-latest'
+          - toolchain: 'nightly'
+            os: 'ubuntu-latest'
+
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: ${{ matrix.toolchain }}
+
+      - run: cargo build --verbose
+      - run: cargo test --verbose
+
+  lint_and_fmt:
+    name: Check format and lint rust crates
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+
+      - run: cargo fmt --all -- --check
+      - run: cargo clippy -- -D warnings
+
+  ci_ok:
+    name: Rust CI OK
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    if: always()
+    needs: [build_and_test, lint_and_fmt]
+    env:
+      FAILURE: ${{ contains(join(needs.*.result, ','), 'failure') }}
+      CANCELLED: ${{ contains(join(needs.*.result, ','), 'cancelled') }}
+    steps:
+      - name: Check for failure or cancelled jobs result
+        shell: bash
+        run: |
+          echo "Failure: $FAILURE - Cancelled: $CANCELLED"
+          if [ "$FAILURE" = "false" ] && [ "$CANCELLED" = "false" ]; then
+            exit 0
+          else
+            exit 1
+          fi

.github/workflows/rust.yml

@@ -1,40 +0,0 @@
-name: Rust CI
-
-on:
-  push:
-    paths:
-      - '.github/**'
-      - 'crates/**'
-  pull_request:
-    paths:
-      - '.github/**'
-      - 'crates/**'
-
-env: 
-  CARGO_TERM_COLOR: always
-
-jobs:
-  lint_and_fmt:
-    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-      - run: cargo fmt --all -- --check
-      - run: cargo clippy -- -D warnings
-
-  build_and_test:
-    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
-    name: Build and test rust crates
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        toolchain:
-          - stable
-          - beta
-          - nightly
-    steps:
-      - uses: actions/checkout@v4
-      - run: rustup update ${{ matrix.toolchain }} && rustup default ${{ matrix.toolchain }}
-      - run: cargo build --verbose
-      - run: cargo test --verbose

.github/workflows/spell-checking.yml

@@ -0,0 +1,70 @@
+name: Spell Checker
+
+on:
+  push:
+    branches:
+      - 'main'
+
+  pull_request:
+
+concurrency:
+  group: '${{ github.workflow }}-${{ github.head_ref || github.ref }}'
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  spell_checking:
+    name: LanguageTool
+    runs-on: ubuntu-latest
+
+    permissions:
+      checks: write
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          # Keep this value in order to show the error comments
+          # also on edited files.
+          fetch-depth: 2
+
+      # If the workflow is triggered by a push use check reporter
+      #
+      # If the workflow is triggered by a PR coming from the
+      # same repository, the author has write access so we can
+      # use pr-review reporter since the GITHUB_TOKEN will have review
+      # write permissions
+      #
+      # Otherwise use annotation reporter that do not require any
+      # particular permission
+      #
+      # Why this?
+      # https://github.com/Valerioageno/tuono/pull/137#pullrequestreview-2455455272
+      - name: Set reporter
+        id: reporter
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          FROM_MAIN_REPO: ${{ github.event.pull_request.head.repo.full_name == github.event.pull_request.base.repo.full_name }}
+        run: |
+          echo "EVENT_NAME: $EVENT_NAME FROM_MAIN_REPO: $FROM_MAIN_REPO"
+          if [ "$EVENT_NAME" == 'push' ]; then
+            echo "name=github-check" >> $GITHUB_OUTPUT
+          elif [ "$FROM_MAIN_REPO" == 'true' ]; then
+            echo "name=github-pr-review" >> $GITHUB_OUTPUT
+          else
+            echo "name=github-pr-annotations" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Review dog languagetool
+        uses: reviewdog/action-languagetool@v1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Change reviewdog reporter if you need [github-pr-check,github-check,github-pr-review].
+          reporter: ${{ steps.reporter.outputs.name }}
+          # Change reporter level if you need.
+          level: 'warning'
+          patterns: '**/*.md **/*.txt **/*.mdx'
+          # enabled_categories: "STYLE,PLAIN_ENGLISH,WHITESPACE_RULE,EN_QUOTES,DASH_RULE,WORD_CONTAINS_UNDERSCORE,UPPERCASE_SENTENCE_START,ARROWS,COMMA_PARENTHESIS_WHITESPACE,UNLIKELY_OPENING_PUNCTUATION,SENTENCE_WHITESPACE,EN_UNPAIRED_BRACKETS,PHRASE_REPETITION,PUNCTUATION_PARAGRAPH_END"
+          disabled_categories: ''
+          disabled_rules: ''

.github/workflows/typescript-ci.yml

@@ -0,0 +1,80 @@
+name: Typescript CI
+
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request:
+
+concurrency:
+  group: '${{ github.workflow }}-${{ github.head_ref || github.ref }}'
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build_and_test:
+    name: Check build and test
+
+    strategy:
+      fail-fast: true
+      matrix:
+        os:
+          - 'ubuntu-latest'
+          - 'macos-latest'
+          - 'windows-latest'
+
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install NodeJS Dependencies
+        uses: ./.github/actions/install-node-dependencies
+
+      - name: Build project
+        run: pnpm build
+
+      - name: Test project
+        run: pnpm test
+
+  lint_and_fmt:
+    name: Check format and lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install NodeJS Dependencies
+        uses: ./.github/actions/install-node-dependencies
+
+      - name: Check formatting
+        run: pnpm format:check
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Types
+        run: pnpm types
+
+  ci_ok:
+    name: Typescript CI OK
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    if: always()
+    needs: [build_and_test, lint_and_fmt]
+    env:
+      FAILURE: ${{ contains(join(needs.*.result, ','), 'failure') }}
+      CANCELLED: ${{ contains(join(needs.*.result, ','), 'cancelled') }}
+    steps:
+      - name: Check for failure or cancelled jobs result
+        shell: bash
+        run: |
+          echo "Failure: $FAILURE - Cancelled: $CANCELLED"
+          if [ "$FAILURE" = "false" ] && [ "$CANCELLED" = "false" ]; then
+            exit 0
+          else
+            exit 1
+          fi

.github/workflows/typescript.yml

@@ -1,66 +0,0 @@
-name: Typescript CI
-
-on:
-  push:
-    paths:
-      - '.github/**'
-      - 'packages/**'
-  pull_request:
-    paths:
-      - '.github/**'
-      - 'packages/**'
-
-jobs:
-  build-and-test:
-    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
-    timeout-minutes: 15
-    runs-on: ubuntu-latest
-    
-    steps:    
-    - name: Check out code
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 2
-
-    - name: Setup Node.js environment
-      uses: actions/setup-node@v4
-      with:
-        node-version: 20
-
-    - name: Install pnpm
-      run: npm i -g pnpm
-        
-    - name: Install dependencies
-      run: pnpm install
-      
-    - name: Build project
-      run: pnpm build
-
-    - name: Test project
-      run: pnpm test
-
-  fmt-lint-and-types:
-    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-
-    steps:    
-    - name: Check out code
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 2
-        
-    - name: Install pnpm
-      run: npm i -g pnpm
-       
-    - name: Install dependencies
-      run: pnpm install
-
-    - name: Check formatting
-      run: pnpm format:check
-      
-    - name: Lint
-      run: pnpm lint
- 
-    - name: Types
-      run: pnpm types

.gitignore

@@ -1,12 +1,14 @@
+## Node related ignores
+
 node_modules/
 dist/
 .turbo/
 
 */**/routeTree.gen.ts
 
-pnpm-lock.yaml
+examples/*/pnpm-lock.yaml
 
-examples/playground/
+vite.config.ts.timestamp*
 
 ## Rust related ignores
 
@@ -24,3 +26,6 @@ examples/playground/
 
 # MSVC Windows builds of rustc generate these, which store debugging information
 *.pdb
+
+# Files, generated by the code editors
+.vscode/

.nvmrc

@@ -1 +1 @@
-v20.10.0
+22.13.1

.prettierignore

@@ -0,0 +1,8 @@
+pnpm-lock.yaml
+
+dist
+.tuono
+
+vite.config.ts.timestamp-*
+
+packages/tuono-lazy-fn-vite-plugin/tests/sources/*

.prettierrc

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://json.schemastore.org/prettierrc",
   "semi": false,
   "singleQuote": true,
   "trailingComma": "all"

CODEOWNERS

@@ -0,0 +1,9 @@
+*          @Valerioageno @marcalexiei
+
+# Rust
+/crates/    @Valerioageno
+/Cargo.toml @Valerioageno
+
+# Misc
+/.github/   @marcalexiei
+

CODE_OF_CONDUCT.md

@@ -2,7 +2,7 @@
 
 ## Our Pledge
 
-We as members, contributors, and leaders pledge to make participation in our
+We, as members, contributors, and leaders, pledge to make participation in our
 community a harassment-free experience for everyone, regardless of age, body
 size, visible or invisible disability, ethnicity, sex characteristics, gender
 identity and expression, level of experience, education, socio-economic status,
@@ -17,23 +17,23 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
   and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the
+- Focusing on what is best, not just for us as individuals, but for the
   overall community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or
-  advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email
+- The use of sexualized language or imagery, and sexual attention or
+  Advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
   address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct that could reasonably be considered inappropriate in a
   professional setting
 
 ## Enforcement Responsibilities
@@ -45,13 +45,13 @@ or harmful.
 
 Community leaders have the right and responsibility to remove, edit, or reject
 comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
+not aligned with this Code of Conduct, and will communicate reasons for moderation
 decisions when appropriate.
 
 ## Scope
 
 This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
+An individual is officially representing the community in public spaces.
 Examples of representing our community include using an official e-mail address,
 posting via an official social media account, or acting as an appointed
 representative at an online or offline event.
@@ -106,7 +106,7 @@ Violating these terms may lead to a permanent ban.
 ### 4. Permanent Ban
 
 **Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior,  harassment of an
+standards, including sustained inappropriate behavior, harassment of an
 individual, or aggression toward or disparagement of classes of individuals.
 
 **Consequence**: A permanent ban from any sort of public interaction within

CONTRIBUTING.md

@@ -1,21 +1,26 @@
-![](https://github.com/Valerioageno/tuono/actions/workflows/rust.yml/badge.svg)
-![](https://github.com/Valerioageno/tuono/actions/workflows/typescript.yml/badge.svg)
+![](https://github.com/tuono-labs/tuono/actions/workflows/rust.yml/badge.svg)
+![](https://github.com/tuono-labs/tuono/actions/workflows/typescript.yml/badge.svg)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-# How to contribute to Tuono
+# How to Contribute to Tuono
+
+## Contributions
 
-## Contributions 
 Any feature contribution or suggestion is strongly appreciated.
-Since the current project size there isn't yet a defined way to start a discussion. Consider to [open a new issue](https://github.com/Valerioageno/tuono/issues/new)
-or to reach me using my email address [valerioageno@yahoo.it](mailto:valerioageno@ahoo.it). I'm also available on twitter (X) DMs @valerioageno.
+
+We are currently managing the tasks' prioritization in the [Road to V1](https://github.com/orgs/tuono-labs/projects/2) project. You can pick any task that you see in the `ready` column that is not already assigned.
+
+If you want to contribute on something that is in the `backlog` column, or it hasn't been scoped yet, please drop a message in the [#general](https://discord.com/invite/khQzPa654B) discord channel so we can all have visibility of it.
+
+Consider [opening a new issue](https://github.com/tuono-labs/tuono/issues/new/choose) if you find a bug.
 
 ## Bugs
 
 **Did you find a bug?**
-- Ensure the bug was not already reported by searching on GitHub under [Issues](https://github.com/Valerioageno/tuono/issues).
-- If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/Valerioageno/tuono/issues/new). Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case demonstrating the expected behavior that is not occurring.
+
+- Ensure the bug was not already reported by searching on GitHub under [Issues](https://github.com/tuono-labs/tuono/issues).
+- If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/tuono-labs/tuono/issues/new/choose). Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case demonstrating the expected behavior that is not occurring.
 
 **Did you write a patch that fixes a bug?**
-- Open a new GitHub pull request with the patch.
-- Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
-- The pull requests must pass all the CI pipelines
+
+[Visit the documentation to learn how to open a pull request](https://tuono.dev/documentation/contributing/pull-requests)

Cargo.toml

@@ -1,12 +1,15 @@
 [workspace]
 resolver = "2"
 members = [
-		"crates/tuono",
-		"crates/tuono_lib",
-		"crates/tuono_lib_macros",
+  "crates/tuono", 
+  "crates/tuono_internal", 
+  "crates/tuono_lib", 
+  "crates/tuono_lib_macros"
 ]
 exclude = [
-		"examples/playground",
-		"examples/tuono",
-		"examples/tutorial"
+  "apps/documentation",
+  "examples/with-mdx",
+  "examples/tuono-app",
+  "examples/tuono-tutorial",
+  "examples/with-tailwind",
 ]

README.md

@@ -1,98 +1,62 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/Valerioageno/tuono/main/assets/logo.png" width="200px">
-</p>
-<h1 align="center">Tuono<br>The react/rust fullstack framework</h1>
-<p align="center">
-⚠️ This project is under heavy development. API might drastically change ⚠️
-</p>
-<div align="center">
-    <img src="https://github.com/Valerioageno/tuono/actions/workflows/rust.yml/badge.svg" />
-    <img src="https://github.com/Valerioageno/tuono/actions/workflows/typescript.yml/badge.svg" />
-</div>
+[Documentation](https://tuono.dev) | [Tutorial](https://tuono.dev/documentation/tutorial) |
+[Discord](https://discord.com/invite/khQzPa654B) | [✨Contributing](https://tuono.dev/documentation/contributing)
 
-<br>
-<br>
+# Tuono
 
+<img align="right" src="https://raw.githubusercontent.com/tuono-labs/tuono/main/assets/logo.png" width="160px">
 
-Tuono (Italian word for "thunder", pronounced /2 Oh No/). 
+![](https://github.com/tuono-labs/tuono/actions/workflows/rust.yml/badge.svg)
+![](https://github.com/tuono-labs/tuono/actions/workflows/typescript.yml/badge.svg)
+
+**Tuono is a full-stack web framework for building React applications using Rust as the backend with
+a strong focus on usability and performance.**
+
+Tuono (Italian word for "thunder", pronounced /2 Oh No/).
 Why Tuono? Just a badass name.
 
-> Check out the [tutorial](https://github.com/Valerioageno/tuono/blob/main/docs/tutorial.md) to get started.
+If you have experience with [Next.js](https://nextjs.org/) you will feel home here.
 
-## Introduction
+Some of its features are:
 
-**NodeJs/Deno/Bun are the only runtimes that allow a React app to be fullstack right? (no)**
+- 🟦 Native Typescript
+- 🌐 Next.js like Routing
+- 🍭 CSS/SCSS modules
+- 🧬 Server Side Rendering
+- 🔥 Hot Module Reload
 
-Tuono is a fullstack React framework with the server side written in Rust. 
-Because of this Tuono is extremely fast and the requests are handled by multithreaded Rust server.
-React is still React - it is just superpowered.
+## Documentation
 
-**Rust is an hard language then writing server side code is hard as well right? (no again)**
+The [documentation](https://tuono.dev/) is available on
+[tuono.dev](https://tuono.dev/).
 
-Tuono provides a collection of utilities to handle the server side code seamlessly with the React code.
-Each server side route is managed with a separate file alongside the React route. The routing is handled
-by Tuono based on the files defined within the `./src/routes` directory.
+## Installation
 
-## Features
+Available on MacOS, Linux and Windows.
 
-- 🟦  Typescript
-- 🌐  Routing
-- 🔥  Hot Module Reload
-- 🍭  CSS modules
-- 🧬  Server Side Rendering
-- 🧵  Multi thread backend
-- ⚙️   Build optimizations
-- Custom APIs*
-- Image optimization*
-- Server streamed content*
-
-> *Development in progress
+```sh
+cargo install tuono
+```
 
 ## Getting started
 
-As already mentioned above I strongly suggest you to take a look at the
-[tutorial](https://github.com/Valerioageno/tuono/blob/main/docs/tutorial.md).
-
-Tuono is basically a CLI that provides all the commands to handle the fullstack project. 
-To download it you need [cargo](https://doc.rust-lang.org/cargo/) which is the [rust](https://www.rust-lang.org/)
-package manager.
-
-To download and install it you just need to run `cargo install tuono`.
-
-To create a new project run `tuono new [NAME]` (optionally you can pass the `--template` flag - check the 
-[examples](https://github.com/Valerioageno/tuono/tree/main/examples) folder).
-
-Then to run the local development environment run inside the project folder `tuono dev`
-
-Finally when the project will be ready to be deployed just run `tuono build` to create the final React assets
-and to set the server project to the `production` mode.
-
-Now to execute it just run `cargo run --release`.
-
-## Requirements
-
-- rust
-- cargo
-- node
-- npm/pnpm/yarn*
-
-> yarn [pnp](https://yarnpkg.com/features/pnp) is not supported yet
-
-## Folder structure
+Create a new project with:
 
+```sh
+tuono new [PROJECT_NAME]
 ```
-├── package.json
-├── public
-├── src
-│   ├── routes
-│   └── styles
-├── Cargo.toml
-├── README.md
-└── tsconfig.json
+
+> You can optionally pass the --template (or -t) flag to directly start from a [template](https://github.com/tuono-labs/tuono/tree/main/examples)
+
+Now just install the dependencies with you favourite JS package manager (i.e. `npm install`) and start the development environment
+
+```sh
+tuono dev
 ```
 
 ## Contributing
+
 Any help or suggestion will be appreciated and encouraged.
+Check the [✨Contributing](https://tuono.dev/documentation/contributing) page
 
 ## License
 

apps/README.md

@@ -0,0 +1 @@
+# Stadalone apps folder

apps/documentation/.env.local

@@ -0,0 +1,4 @@
+VITE_PUBLIC_POSTHOG_KEY=phc_wqyze0qQlWutAwL5RL1Bv83D8bdySCkhcFw9MkTVuI8
+VITE_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
+VITE_ENV=development
+VITE_ENABLE_POSTHOG=false

apps/documentation/.env.production

@@ -0,0 +1,4 @@
+VITE_PUBLIC_POSTHOG_KEY=phc_wqyze0qQlWutAwL5RL1Bv83D8bdySCkhcFw9MkTVuI8
+VITE_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
+VITE_ENV=production
+VITE_ENABLE_POSTHOG=true

apps/documentation/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Documentation Contributing
+
+## Update `tuono` version in `apps/documentation`
+
+Update `tuono` version in the following files
+
+- `.github/workflows/ci-documentation.yml`
+- `.github/workflows/deploy-documentation.yml`
+- `apps/documentation/Cargo.toml`
+- `apps/documentation/package.json`
+
+[Refer to this PR for additional information](https://github.com/tuono-labs/tuono/pull/236/files)
+
+In the future we might:
+
+- move the documentation in a separate repo
+- make a script to perform this operation

apps/documentation/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "tuono"
+version = "0.0.1"
+edition = "2021"
+
+[[bin]]
+name = "tuono"
+path = ".tuono/main.rs"
+
+[dependencies]
+tuono_lib = "0.17.6"
+glob = "0.3.1"
+time = { version = "0.3", features = ["macros"] }
+serde = { version = "1.0.202", features = ["derive"] }

apps/documentation/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "documentation",
+  "description": "The react/rust fullstack framework documentation",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "lint": "eslint .",
+    "format": "prettier --write --ignore-unknown .",
+    "format:check": "prettier --check --ignore-unknown .",
+    "types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@mantine/code-highlight": "7.16.1",
+    "@mantine/core": "7.16.1",
+    "@mantine/hooks": "7.16.1",
+    "@mdx-js/react": "3.1.0",
+    "@tabler/icons-react": "3.28.1",
+    "clsx": "2.1.1",
+    "posthog-js": "^1.215.5",
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
+    "remark-gfm": "4.0.0",
+    "tuono": "npm:tuono@0.17.6"
+  },
+  "devDependencies": {
+    "@mdx-js/rollup": "3.1.0",
+    "@types/react": "19.0.8",
+    "@types/react-dom": "19.0.3",
+    "postcss": "8.5.1",
+    "postcss-preset-mantine": "1.17.0",
+    "postcss-simple-vars": "7.0.1"
+  }
+}

apps/documentation/postcss.config.js

@@ -0,0 +1,14 @@
+export default {
+  plugins: {
+    'postcss-preset-mantine': {},
+    'postcss-simple-vars': {
+      variables: {
+        'mantine-breakpoint-xs': '36em',
+        'mantine-breakpoint-sm': '48em',
+        'mantine-breakpoint-md': '62em',
+        'mantine-breakpoint-lg': '75em',
+        'mantine-breakpoint-xl': '88em',
+      },
+    },
+  },
+}

apps/documentation/public/polyfill-db.json

@@ -0,0 +1,18 @@
+{
+  "polyfills": [
+    {
+      "identifier": "HTMLElement",
+      "import": {
+        "package": "@lit-labs/ssr-dom-shim",
+        "name": "HTMLElement"
+      }
+    },
+    {
+      "identifier": "customElements",
+      "import": {
+        "package": "@lit-labs/ssr-dom-shim",
+        "name": "customElements"
+      }
+    }
+  ]
+}

apps/documentation/public/site.webmanifest

@@ -0,0 +1,19 @@
+{
+  "name": "",
+  "short_name": "",
+  "icons": [
+    {
+      "src": "/android-chrome-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/android-chrome-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    }
+  ],
+  "theme_color": "#ffffff",
+  "background_color": "#ffffff",
+  "display": "standalone"
+}

apps/documentation/src/components/App/App.tsx

@@ -0,0 +1,118 @@
+import type { ReactNode, JSX } from 'react'
+
+import { createTheme, MantineProvider, AppShell } from '@mantine/core'
+
+import type { CSSVariablesResolver } from '@mantine/core'
+import { useDisclosure } from '@mantine/hooks'
+
+import PageWithTOC from '@/components/PageWithTOC'
+import Navbar from '@/components/Navbar'
+import Sidebar from '@/components/Sidebar'
+import MdxProvider from '@/components/MdxProvider'
+
+import '@mantine/core/styles.css'
+import '@mantine/code-highlight/styles.css'
+import Footer from '@/components/Footer'
+
+interface RootRouteProps {
+  children: ReactNode
+}
+
+const theme = createTheme({
+  primaryColor: 'violet',
+  primaryShade: { light: 6, dark: 9 },
+  fontFamily: 'Inter',
+  fontFamilyMonospace: 'Menlo',
+  respectReducedMotion: true,
+  radius: {
+    xs: '4px',
+    sm: '4px',
+    lg: '8px',
+    xl: '8px',
+    md: '8px',
+  },
+  fontSizes: {
+    // 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+    xs: '14px',
+    sm: '14px',
+  },
+  colors: {
+    dark: [
+      '#d5d7e0',
+      '#acaebf',
+      '#8c8fa3',
+      '#666980',
+      '#4d4f66',
+      '#34354a',
+      '#2b2c3d',
+      '#1d1e30',
+      '#0c0d21',
+      '#01010a',
+    ],
+  },
+  headings: {
+    sizes: {
+      h1: {
+        fontSize: '48px',
+      },
+    },
+  },
+  other: {
+    sidebarGrayLight: '#495057',
+    sidebarGrayDark: '#adb5bd',
+    sidebarTextHoverLight: '#212529',
+    sidebarTextHoverDark: '#f8f9fa',
+  },
+})
+
+const resolver: CSSVariablesResolver = (th) => {
+  const {
+    sidebarGrayLight,
+    sidebarTextHoverLight,
+    sidebarGrayDark,
+    sidebarTextHoverDark,
+  } = th.other as Record<string, string>
+
+  return {
+    variables: {},
+    light: {
+      '--mantine-color-footer-bg': th.colors.gray[1],
+      '--mantine-color-sidebar-gray': sidebarGrayLight,
+      '--mantine-color-sidebar-text-hover': sidebarTextHoverLight,
+      '--mantine-color-quote-border': th.colors.violet[1],
+    },
+    dark: {
+      '--mantine-color-footer-bg': th.colors.dark[6],
+      '--mantine-color-sidebar-gray': sidebarGrayDark,
+      '--mantine-color-sidebar-text-hover': sidebarTextHoverDark,
+      '--mantine-color-quote-border': th.colors.violet[9],
+    },
+  }
+}
+
+export default function App({ children }: RootRouteProps): JSX.Element {
+  const [opened, { toggle }] = useDisclosure()
+
+  return (
+    <MantineProvider theme={theme} cssVariablesResolver={resolver}>
+      <AppShell
+        layout="alt"
+        header={{ height: 60 }}
+        navbar={{
+          width: 300,
+          breakpoint: 'sm',
+          collapsed: { mobile: !opened },
+        }}
+      >
+        <Navbar toggle={toggle} />
+        <Sidebar close={toggle} />
+        <AppShell.Main pt={0} px="auto">
+          <MdxProvider>
+            <PageWithTOC>{children}</PageWithTOC>
+          </MdxProvider>
+        </AppShell.Main>
+        <Footer />
+      </AppShell>
+    </MantineProvider>
+  )
+}

apps/documentation/src/components/App/index.ts

@@ -0,0 +1,3 @@
+import App from './App'
+
+export default App

apps/documentation/src/components/Breadcrumbs/Breadcrumbs.tsx

@@ -0,0 +1,87 @@
+import { useMemo, type JSX } from 'react'
+import { Breadcrumbs as MantineBreadcrumbs, Button } from '@mantine/core'
+import { Link } from 'tuono'
+
+import { IconChevronRight, IconBolt } from '@tabler/icons-react'
+
+interface BreadcrumbData {
+  href?: string
+  label: string
+}
+interface BreadcrumbsProps {
+  breadcrumbs: Array<BreadcrumbData>
+}
+
+export default function Breadcrumbs({
+  breadcrumbs = [],
+}: BreadcrumbsProps): JSX.Element {
+  const ldJson = useMemo(() => {
+    const _ldJson = {
+      '@context': 'https://schema.org',
+      '@type': 'BreadcrumbList',
+      itemListElement: [
+        {
+          '@type': 'ListItem',
+          position: 1,
+          name: 'Tuono - The React/Rust fullstack framework',
+          item: 'https://tuono.dev' as string | undefined,
+        },
+      ],
+    }
+
+    _ldJson.itemListElement.push(
+      ...breadcrumbs.map((br, i) => ({
+        '@type': 'ListItem' as const,
+        position: i + 3,
+        name: br.label,
+        item: br.href ? `https://tuono.dev${br.href}` : undefined,
+      })),
+    )
+
+    return _ldJson
+  }, [breadcrumbs])
+
+  return (
+    <>
+      <script type="application/ld+json">
+        {JSON.stringify(ldJson, null, 2)}
+      </script>
+      <MantineBreadcrumbs
+        separator={<IconChevronRight size="1.1rem" stroke={1.5} />}
+        mb="md"
+        mt="md"
+      >
+        <Button href="/" component={Link} variant="subtle" radius="xl" p={5}>
+          <IconBolt />
+        </Button>
+        {breadcrumbs.map((br) => (
+          <BreadcrumbElement href={br.href} label={br.label} key={br.label} />
+        ))}
+      </MantineBreadcrumbs>
+    </>
+  )
+}
+
+interface BreadcrumbElementProps {
+  href?: string
+  label: string
+}
+
+export function BreadcrumbElement({
+  href,
+  label,
+}: BreadcrumbElementProps): JSX.Element {
+  if (href) {
+    return (
+      <Button component={Link} href={href} variant="subtle" radius="xl" px={10}>
+        {label}
+      </Button>
+    )
+  }
+
+  return (
+    <Button component="span" variant="light" radius="xl">
+      {label}
+    </Button>
+  )
+}

apps/documentation/src/components/Breadcrumbs/index.ts

@@ -0,0 +1,3 @@
+import Breadcrumbs from './Breadcrumbs'
+
+export default Breadcrumbs

apps/documentation/src/components/EditPage/EditPage.tsx

@@ -0,0 +1,24 @@
+import type { JSX } from 'react'
+import { Button } from '@mantine/core'
+import { IconEdit } from '@tabler/icons-react'
+import { useRouter } from 'tuono'
+
+const GITHUB_URL =
+  'https://github.com/tuono-labs/tuono/tree/main/apps/documentation/src/routes'
+
+export default function EditPage(): JSX.Element {
+  const { pathname } = useRouter()
+
+  return (
+    <Button
+      p={0}
+      component="a"
+      variant="transparent"
+      leftSection={<IconEdit />}
+      target="_blank"
+      href={`${GITHUB_URL}${pathname}.mdx`}
+    >
+      Edit page
+    </Button>
+  )
+}

apps/documentation/src/components/EditPage/index.ts

@@ -0,0 +1,3 @@
+import EditPage from './EditPage'
+
+export default EditPage

apps/documentation/src/components/Footer/Footer.tsx

@@ -0,0 +1,182 @@
+import type { JSX } from 'react'
+import { Link } from 'tuono'
+import {
+  Container,
+  Box,
+  AppShell,
+  Title,
+  Divider,
+  Flex,
+  Text,
+  Anchor,
+} from '@mantine/core'
+import type { MantineSize } from '@mantine/core'
+
+interface LinkData {
+  title: string
+  url: string
+}
+
+interface FooterLinkListProps {
+  title: string
+  links: Array<LinkData>
+  hiddenFrom?: MantineSize
+}
+
+const aboutLinks: Array<LinkData> = [
+  { title: 'Contribute', url: '/documentation/contributing' },
+  {
+    title: 'GitHub releases',
+    url: 'https://github.com/tuono-labs/tuono/releases',
+  },
+]
+
+const communityLinks: Array<LinkData> = [
+  { title: 'Chat on Discord', url: 'https://discord.com/invite/khQzPa654B' },
+  { title: 'Follow on X', url: 'https://twitter.com/valerioageno' },
+  { title: 'Follow on GitHub', url: 'https://github.com/tuono-labs' },
+]
+
+const legalLinks: Array<LinkData> = [
+  { title: 'Privacy Policy', url: '/policies/privacy' },
+]
+
+function FooterLink({ link }: { link: LinkData }): JSX.Element {
+  const component = link.url.startsWith('http') ? undefined : Link
+  const target = link.url.startsWith('http') ? '_blank' : undefined
+  return (
+    <Box>
+      <Anchor
+        component={component}
+        href={link.url}
+        key={link.url}
+        fz={14}
+        target={target}
+      >
+        {link.title}
+      </Anchor>
+    </Box>
+  )
+}
+
+function FooterLinkList({
+  title,
+  links,
+  hiddenFrom,
+}: FooterLinkListProps): JSX.Element {
+  return (
+    <Box hiddenFrom={hiddenFrom}>
+      <Title order={5} mb={8}>
+        {title}
+      </Title>
+      {links.map((link) => (
+        <FooterLink link={link} key={link.url} />
+      ))}
+    </Box>
+  )
+}
+
+function FooterTitle(): JSX.Element {
+  const size = 44
+  return (
+    <Box mb={24}>
+      <Flex gap={12} align="center" h={size} mb={8}>
+        <img src="/logo.svg" alt="Tuono" width={size} height={size} />
+        <Title order={2} fz={size}>
+          Tuono
+        </Title>
+      </Flex>
+      <Text fz={12}>Simply the fastest full-stack web framework ⚡</Text>
+    </Box>
+  )
+}
+
+function TocPlaceholder(): JSX.Element {
+  return (
+    <Box
+      w={220}
+      miw={220}
+      data-id="table-of-content-placeholder"
+      visibleFrom="lg"
+    />
+  )
+}
+
+function FooterOutro(): JSX.Element {
+  const fontSize = 14
+  return (
+    <Container
+      size={1000}
+      w="100%"
+      display="flex"
+      style={{ gap: 12, justifyContent: 'space-between' }}
+    >
+      <Box w="100%">
+        <Text fz={fontSize}>
+          Built by{' '}
+          <Anchor fz={fontSize} href="https://github.com/Valerioageno">
+            Valerio Ageno
+          </Anchor>{' '}
+          and{' '}
+          <Anchor
+            fz={fontSize}
+            href="https://github.com/tuono-labs/tuono/graphs/contributors"
+          >
+            these awesome people
+          </Anchor>
+        </Text>
+      </Box>
+      <Anchor
+        fz={fontSize}
+        w={150}
+        component={Link}
+        href="/policies/privacy"
+        ta="right"
+        visibleFrom="xs"
+      >
+        Privacy Policy
+      </Anchor>
+      <TocPlaceholder />
+    </Container>
+  )
+}
+
+export default function Footer(): JSX.Element {
+  return (
+    <AppShell.Footer id="app-footer" withBorder={false} zIndex={0} p={0}>
+      <Box m={0} pt={52} pb={8} w="100%" bg="var(--mantine-color-footer-bg)">
+        <Container
+          size={1000}
+          w="100%"
+          display="flex"
+          style={{ gap: 12, justifyContent: 'space-between' }}
+          mb={24}
+        >
+          <Flex
+            justify="space-between"
+            w="100%"
+            direction={{ base: 'column', xs: 'row' }}
+          >
+            <FooterTitle />
+            <Flex
+              gap={{ base: 12, md: 32 }}
+              justify="space-between"
+              direction={{ base: 'column', xs: 'row' }}
+            >
+              <FooterLinkList title="About" links={aboutLinks} />
+              <FooterLinkList title="Community" links={communityLinks} />
+              <FooterLinkList
+                title="Legal"
+                links={legalLinks}
+                hiddenFrom="xs"
+              />
+            </Flex>
+          </Flex>
+          <TocPlaceholder />
+        </Container>
+        <Divider mb={8} mt={28} />
+        <FooterOutro />
+      </Box>
+    </AppShell.Footer>
+  )
+}

apps/documentation/src/components/Footer/index.ts

@@ -0,0 +1,3 @@
+import Footer from './Footer'
+
+export default Footer

apps/documentation/src/components/Hero/Hero.tsx

@@ -0,0 +1,54 @@
+import type { JSX } from 'react'
+import {
+  Button,
+  Center,
+  Container,
+  CopyButton,
+  Group,
+  rem,
+  Text,
+  Title,
+} from '@mantine/core'
+import { IconCopy, IconCheck } from '@tabler/icons-react'
+import { Link } from 'tuono'
+
+export default function Hero(): JSX.Element {
+  return (
+    <Container size={1100} my={100}>
+      <Center>
+        <Title order={1}>Superfast fullstack react framework</Title>
+      </Center>
+      <Center mt={50}>
+        <Text fz="18px">
+          The technologies we love seamlessly working together to unleash the
+          <strong> highest web performance</strong> ever met on React
+        </Text>
+      </Center>
+      <Center mt={50}>
+        <Group>
+          <Button component={Link} href="/documentation" size="lg">
+            Get Started
+          </Button>
+          <CopyButton value="cargo install tuono">
+            {({ copied, copy }) => (
+              <Button
+                onClick={copy}
+                size="lg"
+                style={{ border: 'solid 1px var(--mantine-color-violet-1)' }}
+                color="gray"
+                leftSection="cargo install tuono"
+                rightSection={
+                  copied ? (
+                    <IconCheck style={{ width: rem(20) }} />
+                  ) : (
+                    <IconCopy style={{ width: rem(20) }} />
+                  )
+                }
+              />
+            )}
+          </CopyButton>
+        </Group>
+      </Center>
+    </Container>
+  )
+}

apps/documentation/src/components/Hero/index.ts

@@ -0,0 +1,3 @@
+import Hero from './Hero'
+
+export default Hero

apps/documentation/src/components/MdxProvider/MdxBold/MdxBold.tsx

@@ -0,0 +1,6 @@
+import type { JSX } from 'react'
+import { Text, type TextProps } from '@mantine/core'
+
+export default function MdxBold(props: TextProps): JSX.Element {
+  return <Text component="span" fw={700} {...props} />
+}

apps/documentation/src/components/MdxProvider/MdxBold/index.ts

@@ -0,0 +1,3 @@
+import MdxBold from './MdxBold'
+
+export default MdxBold

apps/documentation/src/components/MdxProvider/MdxCode/MdxCode.tsx

@@ -0,0 +1,8 @@
+import type { JSX, HTMLAttributes } from 'react'
+import { Code } from '@mantine/core'
+
+export default function MdxCode(
+  props: HTMLAttributes<HTMLPreElement>,
+): JSX.Element {
+  return <Code {...props} style={{ fontSize: 'inherit' }} />
+}

apps/documentation/src/components/MdxProvider/MdxCode/index.ts

@@ -0,0 +1,3 @@
+import MdxCode from './MdxCode'
+
+export default MdxCode

apps/documentation/src/components/MdxProvider/MdxLink/MdxLink.tsx

@@ -0,0 +1,44 @@
+import type { JSX, AnchorHTMLAttributes, ReactNode } from 'react'
+import { Anchor } from '@mantine/core'
+import { Link } from 'tuono'
+import { IconExternalLink } from '@tabler/icons-react'
+
+interface MdxLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  children: ReactNode
+}
+
+export default function MdxLink(props: MdxLinkProps): JSX.Element {
+  if (props.href?.startsWith('http') || props.href?.startsWith('mailto')) {
+    return (
+      <Anchor
+        {...props}
+        target="_blank"
+        variant="transparent"
+        display="inline"
+        style={{ fontWeight: 400 }}
+        p={0}
+      >
+        {props.children}
+        <IconExternalLink
+          size="16px"
+          style={{
+            marginLeft: '2px',
+            display: 'inline-block',
+            transform: 'translateY(3px)',
+          }}
+        />
+      </Anchor>
+    )
+  }
+  return (
+    <Anchor
+      component={Link}
+      {...props}
+      target="_blank"
+      variant="transparent"
+      display="inline"
+      style={{ fontWeight: 400 }}
+      p={0}
+    />
+  )
+}

apps/documentation/src/components/MdxProvider/MdxLink/index.ts

@@ -0,0 +1,3 @@
+import MdxLink from './MdxLink'
+
+export default MdxLink

apps/documentation/src/components/MdxProvider/MdxParagraph/MdxParagraph.module.css

@@ -0,0 +1,5 @@
+.text {
+  code {
+    font-size: 0.9rem !important;
+  }
+}

apps/documentation/src/components/MdxProvider/MdxParagraph/MdxParagraph.tsx

@@ -0,0 +1,19 @@
+import type { JSX, HTMLAttributes } from 'react'
+import { Text } from '@mantine/core'
+
+import styles from './MdxParagraph.module.css'
+
+export default function MdxParagraph(
+  props: HTMLAttributes<HTMLParagraphElement>,
+): JSX.Element {
+  return (
+    <Text
+      {...props}
+      className={styles.text}
+      inherit
+      size="md"
+      my={20}
+      fw={300}
+    />
+  )
+}

apps/documentation/src/components/MdxProvider/MdxParagraph/index.ts

@@ -0,0 +1,3 @@
+import MdxParagraph from './MdxParagraph'
+
+export default MdxParagraph

apps/documentation/src/components/MdxProvider/MdxPre/MdxPre.tsx

@@ -0,0 +1,22 @@
+import type { JSX } from 'react'
+import { CodeHighlight } from '@mantine/code-highlight'
+
+interface PreProps {
+  children: {
+    props: {
+      children: string
+      className?: string
+    }
+  }
+}
+
+export default function MdxPre({ children }: PreProps): JSX.Element {
+  return (
+    <CodeHighlight
+      code={children.props.children || ''}
+      style={{ borderRadius: 8, fontWeight: 100 }}
+      language={children.props.className?.replace('language-', '')}
+      my={16}
+    />
+  )
+}

apps/documentation/src/components/MdxProvider/MdxPre/index.ts

@@ -0,0 +1,3 @@
+import MdxPre from './MdxPre'
+
+export default MdxPre

apps/documentation/src/components/MdxProvider/MdxProvider.tsx

@@ -0,0 +1,50 @@
+import type { JSX, ReactNode } from 'react'
+import { MDXProvider } from '@mdx-js/react'
+import { Divider } from '@mantine/core'
+
+import MdxLink from './MdxLink'
+import MdxPre from './MdxPre'
+import MdxQuote from './MdxQuote'
+import MdxCode from './MdxCode'
+import { h } from './MdxTitle'
+import MdxBold from './MdxBold'
+import MdxTable from './MdxTable'
+import MdxUl from './MdxUl'
+import MdxParagraph from './MdxParagraph'
+
+interface MdxProviderProps {
+  children: ReactNode
+}
+
+export default function MdxProvider({
+  children,
+}: MdxProviderProps): JSX.Element {
+  return (
+    <MDXProvider
+      components={{
+        a: MdxLink,
+        pre: MdxPre,
+        blockquote: MdxQuote,
+        code: MdxCode,
+        h1: h(1),
+        h2: h(2),
+        h3: h(3),
+        h4: h(4),
+        h5: h(5),
+        h6: h(6),
+        strong: MdxBold,
+        table: MdxTable,
+        thead: MdxTable.Thead,
+        tbody: MdxTable.Tbody,
+        tr: MdxTable.Tr,
+        th: MdxTable.Th,
+        td: MdxTable.Td,
+        p: MdxParagraph,
+        ul: MdxUl,
+        hr: Divider,
+      }}
+    >
+      {children}
+    </MDXProvider>
+  )
+}

apps/documentation/src/components/MdxProvider/MdxQuote/MdxQuote.tsx

@@ -0,0 +1,18 @@
+import type { JSX, HTMLAttributes } from 'react'
+import { Blockquote } from '@mantine/core'
+
+export default function MdxQuote(
+  props: HTMLAttributes<HTMLQuoteElement>,
+): JSX.Element {
+  return (
+    <Blockquote
+      py={1}
+      px={20}
+      my={16}
+      iconSize={28}
+      {...props}
+      bd="solid 1px var(--mantine-color-quote-border)"
+      style={{ borderRadius: 8 }}
+    />
+  )
+}

apps/documentation/src/components/MdxProvider/MdxQuote/index.ts

@@ -0,0 +1,3 @@
+import MdxQuote from './MdxQuote'
+
+export default MdxQuote

apps/documentation/src/components/MdxProvider/MdxTable/MdxTable.tsx

@@ -0,0 +1,27 @@
+import type { DetailedHTMLProps, TableHTMLAttributes, JSX } from 'react'
+import { Table, ScrollArea } from '@mantine/core'
+
+type MdxTableProps = DetailedHTMLProps<
+  TableHTMLAttributes<HTMLTableElement>,
+  HTMLTableElement
+>
+
+function MdxTable(props: MdxTableProps): JSX.Element {
+  const { children, ...rest } = props
+  return (
+    <ScrollArea type="auto">
+      <Table highlightOnHover {...rest}>
+        {children}
+      </Table>
+    </ScrollArea>
+  )
+}
+
+MdxTable.Thead = Table.Thead
+MdxTable.Tbody = Table.Tbody
+MdxTable.Tr = Table.Tr
+MdxTable.Th = Table.Th
+MdxTable.Td = Table.Td
+MdxTable.Caption = Table.Caption
+
+export default MdxTable

apps/documentation/src/components/MdxProvider/MdxTable/index.ts

@@ -0,0 +1,3 @@
+import MdxTable from './MdxTable'
+
+export default MdxTable

apps/documentation/src/components/MdxProvider/MdxTitle/MdxTitle.tsx

@@ -0,0 +1,111 @@
+import type { ElementType, JSX, MouseEventHandler, ReactNode } from 'react'
+import { useCallback } from 'react'
+import { Title, Anchor, Box } from '@mantine/core'
+import type { TitleProps } from '@mantine/core'
+import { IconLink } from '@tabler/icons-react'
+import { useHover } from '@mantine/hooks'
+
+export default function MdxTitle({
+  children,
+  order,
+  ...rest
+}: TitleProps): JSX.Element {
+  const headingId = getIdFrom(children)
+  const { hovered, ref } = useHover<HTMLHeadingElement>()
+
+  const handleAnchorClick: MouseEventHandler<HTMLAnchorElement> = useCallback(
+    (e) => {
+      e.preventDefault()
+      if (ref.current) {
+        history.pushState(
+          null,
+          '',
+          `#${(ref.current.firstChild as HTMLHeadingElement).id} `,
+        )
+        ref.current.scrollIntoView({
+          behavior: 'instant',
+          block: 'start',
+        })
+      }
+    },
+    [ref],
+  )
+
+  return (
+    <Box
+      ref={ref}
+      data-order={order}
+      style={{
+        scrollMargin: 80,
+        marginTop: order === 1 ? 0 : 20,
+      }}
+      mb={24}
+      {...rest}
+    >
+      <Title
+        data-heading={headingId}
+        id={headingId}
+        data-order={order}
+        display="inline"
+        order={order}
+        style={{
+          scrollMargin: 80,
+          marginTop: order === 1 ? 0 : 20,
+        }}
+        mb={24}
+        {...rest}
+      >
+        {children}
+        {hovered && order !== 1 && (
+          <Anchor
+            onClick={handleAnchorClick}
+            display="inline-flex"
+            ml={8}
+            mb={2}
+            style={{ alignItems: 'center', verticalAlign: 'middle' }}
+          >
+            <IconLink width={20} height={20} />
+          </Anchor>
+        )}
+      </Title>
+    </Box>
+  )
+}
+
+function getIdFrom(children: ReactNode): string {
+  const getTextContent = (node: ReactNode): string => {
+    if (typeof node === 'string') return node
+    if (typeof node === 'object' && node !== null && 'props' in node) {
+      const child = node as { props?: { children?: ReactNode } }
+      return getTextContent(child.props?.children)
+    }
+    return ''
+  }
+
+  const textContent = Array.isArray(children)
+    ? children.map(getTextContent).join('')
+    : getTextContent(children)
+
+  return (
+    textContent
+      // normalize cause tuono build --static to hang
+      // @see https://github.com/tuono-labs/tuono/issues/468
+      // .normalize('NFKD')// separate accented characters into their base form and diacritical marks
+      .replace(/[\u0300-\u036f]/g, '') // remove all the accents
+      .trim()
+      .toLowerCase()
+      .replace(/\./g, '-') // some titles (configuration) contain keypath, so replace dots with hyphens
+      .replace(/[^a-z0-9 -]/g, '') // remove non-alphanumeric characters
+      .replace(/\s+/g, '-') // replace spaces with hyphens
+      .replace(/-+/g, '-') // remove consecutive hyphens
+  )
+}
+
+export const h = (order: 1 | 2 | 3 | 4 | 5 | 6): ElementType<TitleProps> => {
+  function render(props: TitleProps): JSX.Element {
+    return <MdxTitle order={order} {...props} />
+  }
+  render.displayName = 'H'
+
+  return render
+}

apps/documentation/src/components/MdxProvider/MdxTitle/index.ts

@@ -0,0 +1,5 @@
+import MdxTitle, { h } from './MdxTitle'
+
+export default MdxTitle
+
+export { h }

apps/documentation/src/components/MdxProvider/MdxUl/MdxUl.module.css

@@ -0,0 +1,5 @@
+.list {
+  code {
+    font-size: 0.9rem !important;
+  }
+}

apps/documentation/src/components/MdxProvider/MdxUl/MdxUl.tsx

@@ -0,0 +1,20 @@
+import type { HTMLAttributes, JSX } from 'react'
+import { List } from '@mantine/core'
+
+import styles from './MdxUl.module.css'
+
+export default function MdxUl(
+  props: HTMLAttributes<HTMLUListElement>,
+): JSX.Element {
+  return (
+    <List
+      {...props}
+      className={styles.list}
+      my={12}
+      size="md"
+      style={{ listStylePosition: 'outside' }}
+      fw={300}
+      withPadding
+    />
+  )
+}

apps/documentation/src/components/MdxProvider/MdxUl/index.tsx

@@ -0,0 +1,3 @@
+import MdxUl from './MdxUl'
+
+export default MdxUl

apps/documentation/src/components/MdxProvider/index.ts

@@ -0,0 +1,3 @@
+import MdxProvider from './MdxProvider'
+
+export default MdxProvider

apps/documentation/src/components/MetaTags/MetaTags.tsx

@@ -0,0 +1,45 @@
+import type { ReactNode } from 'react'
+
+interface MetaTagsProps {
+  title: string
+  description?: string
+  type?: 'website' | 'article' | 'book' | 'video.movie' | 'music.song'
+  canonical: string
+}
+
+export default function MetaTags({
+  title,
+  description,
+  type = 'article',
+  canonical,
+}: MetaTagsProps): ReactNode {
+  return (
+    <>
+      <title>{title}</title>
+      <link rel="canonical" href={canonical} />
+      <meta
+        name="description"
+        content={
+          description ??
+          'The technologies we love seamlessly working together to unleash the highest web performance ever met on React'
+        }
+      />
+      <meta
+        name="keywords"
+        content="ReactJs, Typescript, Rust, JavaScript, Fullstack framework, Web development"
+      />
+      <meta property="og:title" content={title} />
+      <meta property="og:type" content={type} />
+      <meta property="og:image" content="https://tuono.dev/og-cover.png" />
+      <meta property="og:url" content={canonical} />
+      <meta property="og:description" content={description} />
+      <meta property="og:site_name" content="Tuono" />
+      <meta property="og:locale" content="en_US" />
+      <meta name="twitter:card" content="summary_large_image" />
+      <meta name="twitter:site" content="@tuono_dev" />
+      <meta name="twitter:title" content={title} />
+      <meta name="twitter:description" content={description} />
+      <meta name="twitter:image" content="https://tuono.dev/og-cover.png" />
+    </>
+  )
+}

apps/documentation/src/components/MetaTags/index.ts

@@ -0,0 +1,3 @@
+import MetaTags from './MetaTags'
+
+export default MetaTags

apps/documentation/src/components/Navbar/Navbar.tsx

@@ -0,0 +1,33 @@
+import type { JSX } from 'react'
+import { AppShell, Box, Burger, Button, Flex } from '@mantine/core'
+import { Link } from 'tuono'
+
+import NavbarActions from './NavbarActions'
+
+interface NavbarProps {
+  toggle: () => void
+}
+
+export default function Navbar({ toggle }: NavbarProps): JSX.Element {
+  return (
+    <AppShell.Header p="sm">
+      <Flex justify="space-between">
+        <Button
+          component={Link}
+          href="/"
+          variant="transparent"
+          p={0}
+          fz={28}
+          hiddenFrom="sm"
+        >
+          Tuono
+        </Button>
+        <Box />
+        <Flex align="center" gap={8}>
+          <NavbarActions />
+          <Burger onClick={toggle} hiddenFrom="sm" size="sm" />
+        </Flex>
+      </Flex>
+    </AppShell.Header>
+  )
+}

apps/documentation/src/components/Navbar/NavbarActions.tsx

@@ -0,0 +1,35 @@
+import type { JSX } from 'react'
+import { Flex, ActionIcon, Group } from '@mantine/core'
+import { IconBrandGithub, IconBrandDiscord } from '@tabler/icons-react'
+
+import ThemeBtn from '../ThemeBtn'
+
+export default function NavbarActions(): JSX.Element {
+  return (
+    <Flex gap={8}>
+      <Group gap={8}>
+        <ActionIcon
+          variant="default"
+          size="lg"
+          aria-label="Check the project on github"
+          href="https://github.com/tuono-labs/tuono"
+          target="_blank"
+          component="a"
+        >
+          <IconBrandGithub />
+        </ActionIcon>
+        <ActionIcon
+          variant="default"
+          size="lg"
+          aria-label="Join the Tuono's community on Discord!"
+          href="https://discord.com/invite/khQzPa654B"
+          target="_blank"
+          component="a"
+        >
+          <IconBrandDiscord />
+        </ActionIcon>
+      </Group>
+      <ThemeBtn />
+    </Flex>
+  )
+}

apps/documentation/src/components/Navbar/index.ts

@@ -0,0 +1,3 @@
+import Navbar from './Navbar'
+
+export default Navbar

apps/documentation/src/components/NavigationButtons/NavigationButtons.tsx

@@ -0,0 +1,62 @@
+import type { JSX } from 'react'
+import { Box, Button, Text, Title, Flex } from '@mantine/core'
+import { IconArrowRight, IconArrowLeft } from '@tabler/icons-react'
+import { Link } from 'tuono'
+
+interface NavigationButtonData {
+  href: string
+  title: string
+}
+
+interface NavigationButtonsProps {
+  prev?: NavigationButtonData
+  next?: NavigationButtonData
+}
+
+export default function NavigationButtons({
+  prev,
+  next,
+}: NavigationButtonsProps): JSX.Element {
+  return (
+    <Flex mt={50} gap={10}>
+      {prev && <NavigationBtn type="prev" {...prev} />}
+      {next && <NavigationBtn type="next" {...next} />}
+    </Flex>
+  )
+}
+
+interface NavigationBtnProps extends NavigationButtonData {
+  type: 'next' | 'prev'
+}
+
+const NavigationBtn = ({
+  type,
+  title,
+  href,
+}: NavigationBtnProps): JSX.Element => {
+  const heading = type === 'next' ? 'Next' : 'Previous'
+  const textAlign = type === 'next' ? 'left' : 'right'
+
+  return (
+    <Button
+      component={Link}
+      fullWidth
+      variant="outline"
+      href={href}
+      justify="space-between"
+      h="auto"
+      rightSection={type === 'next' && <IconArrowRight />}
+      leftSection={type === 'prev' && <IconArrowLeft />}
+      p="20"
+    >
+      <Box>
+        <Title component="span" display="block" order={4} style={{ textAlign }}>
+          {heading}
+        </Title>
+        <Text component="span" display="block" style={{ textAlign }}>
+          {title}
+        </Text>
+      </Box>
+    </Button>
+  )
+}

apps/documentation/src/components/NavigationButtons/index.ts

@@ -0,0 +1,3 @@
+import NavigationButtons from './NavigationButtons'
+
+export default NavigationButtons

apps/documentation/src/components/PageWithTOC/PageWithTOC.module.css

@@ -0,0 +1,9 @@
+.wrapper {
+  width: calc(100% - 220px);
+  word-wrap: break-word;
+
+  /* var(--mantine-breakpoint-md) = 62em */
+  @media (max-width: 62em) {
+    width: 100%;
+  }
+}

apps/documentation/src/components/PageWithTOC/PageWithTOC.tsx

@@ -0,0 +1,62 @@
+import type { JSX, ReactNode } from 'react'
+import { useEffect, useRef, useState } from 'react'
+import { Box, Container } from '@mantine/core'
+import { useViewportSize } from '@mantine/hooks'
+
+import TableOfContents from '@/components/TableOfContents'
+
+import classes from './PageWithTOC.module.css'
+
+interface PageWithTOCProps {
+  children: ReactNode
+}
+
+export function PageWithTOC({ children }: PageWithTOCProps): JSX.Element {
+  const { width } = useViewportSize()
+  const [footerHeight, setFooterHeight] = useState<number>(0)
+  const mainRef = useRef<HTMLDivElement>(null)
+  const height = `calc(100% - ${footerHeight}px)`
+
+  useEffect(() => {
+    const footer = document.getElementById('app-footer')
+
+    if (footer) {
+      setFooterHeight(footer.clientHeight)
+    }
+  }, [
+    setFooterHeight,
+    // Reload on window width resize
+    width,
+  ])
+
+  return (
+    <>
+      <Box
+        style={{ zIndex: 10, height }}
+        pos="relative"
+        ref={mainRef}
+        mb={footerHeight}
+        bg="var(--mantine-color-body)"
+      >
+        <Container
+          size={1000}
+          w="100%"
+          display="flex"
+          style={{ gap: 12, justifyContent: 'space-between' }}
+        >
+          <Box
+            id="mdx-root"
+            component="article"
+            mt="xl"
+            py={36}
+            className={classes.wrapper}
+          >
+            {children}
+          </Box>
+
+          <TableOfContents />
+        </Container>
+      </Box>
+    </>
+  )
+}

apps/documentation/src/components/PageWithTOC/index.ts

@@ -0,0 +1,3 @@
+import { PageWithTOC } from './PageWithTOC'
+
+export default PageWithTOC

apps/documentation/src/components/PostHog/PostHogPageView.tsx

@@ -0,0 +1,20 @@
+import { useEffect } from 'react'
+import { usePostHog } from 'posthog-js/react'
+import { useRouter } from 'tuono'
+
+export default function PostHogPageView(): null {
+  const { pathname } = useRouter()
+  const posthog = usePostHog()
+
+  // Track pageviews
+  useEffect(() => {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (pathname && posthog) {
+      const url = window.origin + pathname
+
+      posthog.capture('$pageview', { $current_url: url })
+    }
+  }, [pathname, posthog])
+
+  return null
+}

apps/documentation/src/components/PostHog/PostHogProvider.tsx

@@ -0,0 +1,31 @@
+import type { JSX, ReactNode } from 'react'
+import { useEffect } from 'react'
+import { PostHogProvider as PostHogLibraryProvider } from 'posthog-js/react'
+import posthogJs from 'posthog-js'
+
+interface PostHogProviderProps {
+  children: ReactNode
+}
+
+export default function PostHogProvider({
+  children,
+}: PostHogProviderProps): JSX.Element {
+  useEffect(() => {
+    if (import.meta.env.VITE_ENABLE_POSTHOG === 'true') {
+      posthogJs.init(import.meta.env.VITE_PUBLIC_POSTHOG_KEY, {
+        api_host: import.meta.env.VITE_PUBLIC_POSTHOG_HOST,
+        persistence: 'memory', // Cookieless tracking
+        disable_persistence: true, // Disable persistence
+        loaded: (ph) => {
+          if (import.meta.env.VITE_ENV === 'development') ph.debug()
+        },
+      })
+    }
+  }, [])
+
+  return (
+    <PostHogLibraryProvider client={posthogJs}>
+      {children}
+    </PostHogLibraryProvider>
+  )
+}

apps/documentation/src/components/PostHog/index.ts

@@ -0,0 +1,4 @@
+import PostHogProvider from './PostHogProvider'
+import PostHogPageView from './PostHogPageView'
+
+export { PostHogProvider, PostHogPageView }

apps/documentation/src/components/Sidebar/Sidebar.tsx

@@ -0,0 +1,111 @@
+import type { JSX } from 'react'
+
+import {
+  AppShell,
+  Badge,
+  Flex,
+  Divider,
+  Title,
+  Button,
+  ScrollArea,
+  Text,
+} from '@mantine/core'
+
+import { IconX } from '@tabler/icons-react'
+import { useMediaQuery } from '@mantine/hooks'
+
+import { sidebarElements } from './sidebarElements'
+import SidebarLink from './SidebarLink'
+
+interface SidebarProps {
+  close: () => void
+}
+
+function SidebarHeader({ close }: SidebarProps): JSX.Element {
+  const isSm = useMediaQuery('(min-width: 48em)')
+  return (
+    <AppShell.Section>
+      <Flex mb={20} w="100%" justify="space-between">
+        <Flex
+          gap={10}
+          align="center"
+          w={isSm ? '100%' : 'auto'}
+          justify="center"
+        >
+          <Title order={3}>Tuono</Title>
+          <Badge mt={4} size="xs" variant="outline">
+            Docs
+          </Badge>
+        </Flex>
+        <Button onClick={close} hiddenFrom="sm" variant="transparent" p="0">
+          <IconX />
+        </Button>
+      </Flex>
+    </AppShell.Section>
+  )
+}
+
+function SidebarElements({ close }: SidebarProps): JSX.Element {
+  return (
+    <AppShell.Section component={ScrollArea}>
+      {sidebarElements.map((el, i) => {
+        if (el.type === 'divider') {
+          return <Divider key={`${el.type}-${i}`} my="md" mx={10} />
+        }
+
+        if (el.type === 'title') {
+          return (
+            <Text
+              key={`${el.type}-${i}`}
+              size="xs"
+              fw={700}
+              fz={12}
+              pl={12}
+              py={5}
+            >
+              {el.label}
+            </Text>
+          )
+        }
+
+        if (el.children?.length) {
+          return (
+            <SidebarLink
+              key={`${el.type}-${i}`}
+              href={el.href}
+              label={el.label}
+              leftSection={el.leftIcon}
+            >
+              {el.children.map((child, index) => (
+                <SidebarLink
+                  href={child.href}
+                  label={child.label}
+                  key={index}
+                  onClick={close}
+                />
+              ))}
+            </SidebarLink>
+          )
+        }
+
+        return (
+          <SidebarLink
+            key={`${el.type}-${i}`}
+            href={el.href}
+            label={el.label}
+            onClick={close}
+          />
+        )
+      })}
+    </AppShell.Section>
+  )
+}
+
+export default function Sidebar({ close }: SidebarProps): JSX.Element {
+  return (
+    <AppShell.Navbar p="md">
+      <SidebarHeader close={close} />
+      <SidebarElements close={close} />
+    </AppShell.Navbar>
+  )
+}

apps/documentation/src/components/Sidebar/SidebarLink.module.css

@@ -0,0 +1,17 @@
+.link {
+  border-radius: 8px;
+  margin-top: 0.25rem;
+  line-height: 1rem;
+  font-weight: 500;
+  transition: 0.3s;
+}
+
+.link span {
+  font-size: 14px !important;
+  color: var(--mantine-color-sidebar-gray);
+}
+
+.link:hover span,
+.active span {
+  color: var(--mantine-color-sidebar-text-hover);
+}

apps/documentation/src/components/Sidebar/SidebarLink.tsx

@@ -0,0 +1,42 @@
+import type { JSX, ReactNode } from 'react'
+import { NavLink, type NavLinkProps } from '@mantine/core'
+import clsx from 'clsx'
+import { Link, useRouter } from 'tuono'
+import { IconChevronRight } from '@tabler/icons-react'
+
+import styles from './SidebarLink.module.css'
+
+interface SidebarLinkProps {
+  label: string
+  href: string
+  onClick?: () => void
+  children?: ReactNode
+}
+
+export default function SidebarLink(
+  props: SidebarLinkProps & NavLinkProps,
+): JSX.Element {
+  const { pathname } = useRouter()
+
+  const isActive = pathname === props.href
+
+  const internalProps = {
+    active: isActive,
+    className: clsx(styles.link, isActive && styles.active),
+    rightSection: props.children && (
+      <IconChevronRight
+        size="1.2rem"
+        stroke={1.5}
+        className="mantine-rotate-rtl"
+      />
+    ),
+    autoContrast: true,
+    ...props,
+  }
+
+  if (props.href.startsWith('#')) {
+    return <NavLink component="button" {...internalProps} />
+  }
+
+  return <NavLink component={Link} {...internalProps} />
+}

apps/documentation/src/components/Sidebar/index.ts

@@ -0,0 +1,3 @@
+import Sidebar from './Sidebar'
+
+export default Sidebar

apps/documentation/src/components/Sidebar/sidebarElements.ts

@@ -0,0 +1,260 @@
+import type { ReactNode } from 'react'
+
+interface SidebarElementBase<T extends string> {
+  type: T
+}
+
+type SidebarDivider = SidebarElementBase<'divider'>
+
+interface SidebarLink extends SidebarElementBase<'element'> {
+  label: string
+  href: string
+  children?: Array<SidebarLink>
+  leftIcon?: ReactNode
+}
+
+interface SidebarTitle extends SidebarElementBase<'title'> {
+  label: string
+}
+
+type SidebarElement = SidebarDivider | SidebarLink | SidebarTitle
+
+export const sidebarElements: Array<SidebarElement> = [
+  {
+    type: 'element',
+    label: 'Home',
+    href: '/',
+  },
+  {
+    type: 'element',
+    label: 'Getting started',
+    href: '#focus',
+    children: [
+      {
+        type: 'element',
+        label: 'Installation',
+        href: '/documentation/getting-started/installation',
+      },
+      {
+        type: 'element',
+        label: 'Setup project',
+        href: '/documentation/getting-started/setup-project',
+      },
+    ],
+  },
+  {
+    type: 'element',
+    label: 'Tutorial',
+    href: '#focus',
+    children: [
+      {
+        type: 'element',
+        href: '/documentation/tutorial',
+        label: 'Intro',
+      },
+      {
+        type: 'element',
+        href: '/documentation/tutorial/development-setup',
+        label: 'Development setup',
+      },
+      {
+        type: 'element',
+        href: '/documentation/tutorial/api-fetching',
+        label: 'API fetching',
+      },
+      {
+        type: 'element',
+        href: '/documentation/tutorial/components',
+        label: 'Components',
+      },
+      {
+        type: 'element',
+        href: '/documentation/tutorial/dynamic-routes',
+        label: 'Dynamic routes',
+      },
+      {
+        type: 'element',
+        href: '/documentation/tutorial/error-handling',
+        label: 'Error handling',
+      },
+      {
+        type: 'element',
+        href: '/documentation/tutorial/seo',
+        label: 'SEO and meta tags',
+      },
+      {
+        type: 'element',
+        href: '/documentation/tutorial/redirections',
+        label: 'Redirections',
+      },
+      {
+        type: 'element',
+        href: '/documentation/tutorial/production',
+        label: 'Production build',
+      },
+      {
+        type: 'element',
+        href: '/documentation/tutorial/conclusion',
+        label: 'Conclusion',
+      },
+    ],
+  },
+  { type: 'divider' },
+  { type: 'title', label: 'Overview' },
+  {
+    type: 'element',
+    label: 'Routing',
+    href: '#focus',
+    children: [
+      {
+        type: 'element',
+        label: 'Pages and layout',
+        href: '/documentation/routing/defining-routes',
+      },
+      {
+        type: 'element',
+        label: 'Dynamic routes',
+        href: '/documentation/routing/dynamic-routes',
+      },
+      {
+        type: 'element',
+        label: 'Link and navigation',
+        href: '/documentation/routing/link-and-navigation',
+      },
+    ],
+  },
+  {
+    type: 'element',
+    label: 'Rendering',
+    href: '#focus',
+    children: [
+      {
+        type: 'element',
+        label: 'Server side rendering (SSR)',
+        href: '/documentation/rendering/server-side-rendering',
+      },
+      {
+        type: 'element',
+        label: 'Static site generation (SSG)',
+        href: '/documentation/rendering/static-site-generation',
+      },
+    ],
+  },
+  {
+    type: 'element',
+    label: 'Styles',
+    href: '#focus',
+    children: [
+      {
+        type: 'element',
+        label: 'CSS modules',
+        href: '/documentation/styles/css-modules',
+      },
+      {
+        type: 'element',
+        label: 'Tailwind CSS',
+        href: '/documentation/styles/tailwind-css',
+      },
+    ],
+  },
+  {
+    type: 'element',
+    label: 'Integrations',
+    href: '#focus',
+    children: [
+      {
+        type: 'element',
+        label: 'MDX',
+        href: '/documentation/integrations/mdx',
+      },
+    ],
+  },
+  { type: 'divider' },
+  { type: 'title', label: 'API reference' },
+  {
+    type: 'element',
+    label: 'Components',
+    href: '#focus',
+    children: [
+      {
+        type: 'element',
+        label: 'Link',
+        href: '/documentation/components/link',
+      },
+    ],
+  },
+  {
+    type: 'element',
+    label: 'Functions',
+    href: '#focus',
+    children: [
+      {
+        type: 'element',
+        label: 'useRouter',
+        href: '/documentation/functions/use-router',
+      },
+      {
+        type: 'element',
+        label: 'dynamic',
+        href: '/documentation/functions/dynamic',
+      },
+    ],
+  },
+  {
+    type: 'element',
+    label: 'Server utilities',
+    href: '#focus',
+    children: [
+      {
+        type: 'element',
+        label: 'Response',
+        href: '/documentation/server-utilities/response',
+      },
+      {
+        type: 'element',
+        label: 'Request',
+        href: '/documentation/server-utilities/request',
+      },
+    ],
+  },
+  {
+    type: 'element',
+    label: 'CLI',
+    href: '/documentation/cli',
+  },
+  {
+    type: 'element',
+    label: 'Application state',
+    href: '/documentation/application-state',
+  },
+  {
+    type: 'element',
+    label: 'Configuration',
+    href: '/documentation/configuration',
+  },
+
+  { type: 'divider' },
+  {
+    type: 'element',
+    label: 'Contributing',
+    href: '#focus',
+    leftIcon: '✨',
+    children: [
+      {
+        type: 'element',
+        label: 'Guildelines',
+        href: '/documentation/contributing',
+      },
+      {
+        type: 'element',
+        label: 'Local development',
+        href: '/documentation/contributing/local-development',
+      },
+      {
+        type: 'element',
+        label: 'Pull requests',
+        href: '/documentation/contributing/pull-requests',
+      },
+    ],
+  },
+]

apps/documentation/src/components/TableOfContents/TableOfContents.module.css

@@ -0,0 +1,106 @@
+.wrapper {
+  position: sticky;
+  top: var(--mantine-spacing-xl);
+  padding-top: 55px;
+  flex: 0 0 calc(250px - 20px);
+  min-width: 220px;
+  max-width: 220px;
+  height: 100vh;
+
+  /* var(--mantine-breakpoint-md) = 62em */
+  @media (max-width: 62em) {
+    display: none;
+  }
+}
+
+.link {
+  white-space: normal;
+  word-wrap: break-word;
+  overflow-wrap: break-word;
+  display: block;
+  border-left: 1px solid transparent;
+  padding: 8px var(--mantine-spacing-md);
+  margin-left: -1px;
+  border-top-right-radius: var(--mantine-radius-sm);
+  border-bottom-right-radius: var(--mantine-radius-sm);
+
+  @mixin light {
+    color: var(--mantine-color-gray-7);
+  }
+
+  @mixin dark {
+    color: var(--mantine-color-dark-1);
+  }
+
+  @mixin rtl {
+    border-left: 0;
+    border-right: 1px solid transparent;
+    margin-left: 0;
+    margin-right: -1px;
+    border-radius: var(--mantine-radius-sm) 0 0 var(--mantine-radius-sm);
+  }
+
+  &:hover {
+    border-color: var(--mantine-color-violet-1);
+
+    @mixin light {
+      color: var(--mantine-color-black);
+    }
+
+    @mixin dark {
+      color: var(--mantine-color-violet-1);
+    }
+  }
+
+  &[data-active] {
+    border-color: var(--mantine-color-violet-5);
+
+    @mixin light {
+      color: var(--mantine-color-violet-8);
+    }
+
+    @mixin dark {
+      color: var(--mantine-color-violet-1);
+    }
+  }
+}
+
+.inner {
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+}
+
+.title {
+  margin-left: var(--mantine-spacing-md);
+
+  @mixin rtl {
+    margin-left: 0;
+    margin-right: var(--mantine-spacing-md);
+  }
+}
+
+.items {
+  border-left: 1px solid;
+
+  @mixin light {
+    border-color: var(--mantine-color-gray-3) !important;
+  }
+
+  @mixin dark {
+    border-color: var(--mantine-color-dark-4) !important;
+  }
+
+  @mixin rtl {
+    border-left: 0;
+    border-right: 1px solid;
+
+    @mixin light {
+      border-color: var(--mantine-color-gray-3) !important;
+    }
+
+    @mixin dark {
+      border-color: var(--mantine-color-dark-4) !important;
+    }
+  }
+}