docs: update project README with detailed structure
This commit is contained in:
parent
05ee36b593
commit
0da0b38313
218
README.md
218
README.md
@ -1,159 +1,103 @@
|
|||||||
# Turborepo starter
|
# Thob Capability Mapping Sprint
|
||||||
|
|
||||||
This Turborepo starter is maintained by the Turborepo core team.
|
A professional benchmarking repository designed to evaluate the current capabilities, strengths, and limitations of the **Thob 3D Builder** compared to industry-standard 3D web frameworks (**Vanilla Three.js** and **React Three Fiber**).
|
||||||
|
|
||||||
## Using this example
|
---
|
||||||
|
|
||||||
Run the following command:
|
## Project Overview
|
||||||
|
This sprint focuses on mapping 3D "Capabilities"—from simple visual changes to complex interactive states—across three primary implementation strategies:
|
||||||
|
1. **Vanilla Three.js**: Imperative, pure-code implementation.
|
||||||
|
2. **React Three Fiber (R3F)**: Declarative, component-based implementation.
|
||||||
|
3. **Thob Page Builder**: No-code/Visual 3D editor experience.
|
||||||
|
|
||||||
```sh
|
---
|
||||||
npx create-turbo@latest
|
|
||||||
|
## Project Structure
|
||||||
|
The repository is organized by "Weeks," with each week containing multiple task benchmarks.
|
||||||
|
```text
|
||||||
|
/
|
||||||
|
├── Week-1/
|
||||||
|
│ ├── Task-1/ (Material Color Change)
|
||||||
|
│ │ ├── vanilla/ ← Imperative Three.js setup
|
||||||
|
│ │ ├── r3f/ ← Declarative React setup
|
||||||
|
│ │ ├── thob/ ← Builder Exploration Notes
|
||||||
|
│ │ └── report.md ← Comparative Capability Report
|
||||||
|
│ ├── Task-2/ (Texture Mapping)
|
||||||
|
│ │ ├── vanilla/ ← TextureLoader implementation
|
||||||
|
│ │ ├── r3f/ ← useLoader implementation
|
||||||
|
│ │ ├── thob/ ← Texture workflow observations
|
||||||
|
│ │ └── report.md ← Comparative Capability Report
|
||||||
|
│ ├── Task-3/ (Hover Interaction)
|
||||||
|
│ │ ├── vanilla/ ← Raycaster-based hover
|
||||||
|
│ │ ├── r3f/ ← onPointerOver/Out events
|
||||||
|
│ │ ├── thob/ ← Interaction engine gap notes
|
||||||
|
│ │ └── report.md ← Comparative Capability Report
|
||||||
|
│ ├── Task-4/ (Click Toggle State)
|
||||||
|
│ │ ├── vanilla/ ← Click-to-state raycasting
|
||||||
|
│ │ ├── r3f/ ← onClick state management
|
||||||
|
│ │ ├── thob/ ← Persistent state limitation notes
|
||||||
|
│ │ └── report.md ← Comparative Capability Report
|
||||||
|
│ ├── GeneralNotes.md ← Strategic Overview
|
||||||
|
│ └── Week-1-PersonalSummary.md ← Personal Narrative
|
||||||
|
└── README.md
|
||||||
```
|
```
|
||||||
|
|
||||||
## What's inside?
|
---
|
||||||
|
|
||||||
This Turborepo includes the following packages/apps:
|
## 🛠️ Tech Stack
|
||||||
|
* **Engine**: Three.js
|
||||||
|
* **Frontend**: React (for R3F)
|
||||||
|
* **Styling**: CSS Modules / Vanilla CSS
|
||||||
|
* **Build Tool**: Vite
|
||||||
|
* **Platform**: Thob 3D Page Builder
|
||||||
|
|
||||||
### Apps and Packages
|
---
|
||||||
|
|
||||||
- `docs`: a [Next.js](https://nextjs.org/) app
|
## 🏁 Week 1 Milestone Summary
|
||||||
- `web`: another [Next.js](https://nextjs.org/) app
|
|
||||||
- `@repo/ui`: a stub React component library shared by both `web` and `docs` applications
|
|
||||||
- `@repo/eslint-config`: `eslint` configurations (includes `eslint-config-next` and `eslint-config-prettier`)
|
|
||||||
- `@repo/typescript-config`: `tsconfig.json`s used throughout the monorepo
|
|
||||||
|
|
||||||
Each package/app is 100% [TypeScript](https://www.typescriptlang.org/).
|
| Task | Capability | Vanilla | R3F | Thob Builder |
|
||||||
|
| :--- | :--- | :--- | :--- | :--- |
|
||||||
|
| **01** | Material Color | Yes | Yes | Yes (Static) |
|
||||||
|
| **02** | Texture Mapping | Yes | Yes | Yes (Fastest) |
|
||||||
|
| **03** | Hover Interaction | Yes | Yes | Planned / Limited |
|
||||||
|
| **04** | Click Toggle State | Yes | Yes | Unstable / Broken |
|
||||||
|
|
||||||
### Utilities
|
### 🔦 Key Week 1 Insights:
|
||||||
|
* **Speed Advantage**: Thob Builder is exceptionally fast for **Static Visual Configuration**. Setting up meshes and textures in the UI is roughly **3-5x faster** than writing the equivalent boilerplate in code.
|
||||||
|
* **Interaction Gap**: The primary limitation currently identified is the **Interaction Engine**. Hover events and persistent state toggles (onClick) are currently unreliable or missing in the builder.
|
||||||
|
|
||||||
This Turborepo has some additional tools already setup for you:
|
---
|
||||||
|
|
||||||
- [TypeScript](https://www.typescriptlang.org/) for static type checking
|
## 🚀 Getting Started
|
||||||
- [ESLint](https://eslint.org/) for code linting
|
|
||||||
- [Prettier](https://prettier.io) for code formatting
|
|
||||||
|
|
||||||
### Build
|
### 📦 Installation
|
||||||
|
The project uses `yarn` for dependency management.
|
||||||
|
```bash
|
||||||
|
# Clone the repository
|
||||||
|
git clone [repo-url]
|
||||||
|
|
||||||
To build all apps and packages, run the following command:
|
# Install all dependencies (Monorepo root)
|
||||||
|
yarn install
|
||||||
With [global `turbo`](https://turborepo.dev/docs/getting-started/installation#global-installation) installed (recommended):
|
|
||||||
|
|
||||||
```sh
|
|
||||||
cd my-turborepo
|
|
||||||
turbo build
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Without global `turbo`, use your package manager:
|
### 💻 Development Servers
|
||||||
|
To run any specific task implementation:
|
||||||
```sh
|
```bash
|
||||||
cd my-turborepo
|
# Example: Running Task 4 (R3F)
|
||||||
npx turbo build
|
cd Week-1/Task-4/r3f
|
||||||
yarn dlx turbo build
|
yarn dev
|
||||||
pnpm exec turbo build
|
|
||||||
```
|
```
|
||||||
|
|
||||||
You can build a specific package by using a [filter](https://turborepo.dev/docs/crafting-your-repository/running-tasks#using-filters):
|
---
|
||||||
|
|
||||||
With [global `turbo`](https://turborepo.dev/docs/getting-started/installation#global-installation) installed:
|
## Contribution & Reporting
|
||||||
|
Each task includes a **`report.md`** file. These reports follow a standardized format to capture:
|
||||||
|
* **Complexity**: How many lines of code vs. clicks?
|
||||||
|
* **Limitation Type**: Is it a runtime, editor, or UX issue?
|
||||||
|
* **Workarounds**: How did we solve the gap?
|
||||||
|
* **Business Value**: Why does this feature matter to our users?
|
||||||
|
|
||||||
```sh
|
---
|
||||||
turbo build --filter=docs
|
|
||||||
```
|
|
||||||
|
|
||||||
Without global `turbo`:
|
**Sprint Lead**: Divya Pahuja
|
||||||
|
**Goal**: Identify the "Interactivity Threshold" where code becomes more efficient than the builder UI.
|
||||||
```sh
|
|
||||||
npx turbo build --filter=docs
|
|
||||||
yarn exec turbo build --filter=docs
|
|
||||||
pnpm exec turbo build --filter=docs
|
|
||||||
```
|
|
||||||
|
|
||||||
### Develop
|
|
||||||
|
|
||||||
To develop all apps and packages, run the following command:
|
|
||||||
|
|
||||||
With [global `turbo`](https://turborepo.dev/docs/getting-started/installation#global-installation) installed (recommended):
|
|
||||||
|
|
||||||
```sh
|
|
||||||
cd my-turborepo
|
|
||||||
turbo dev
|
|
||||||
```
|
|
||||||
|
|
||||||
Without global `turbo`, use your package manager:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
cd my-turborepo
|
|
||||||
npx turbo dev
|
|
||||||
yarn exec turbo dev
|
|
||||||
pnpm exec turbo dev
|
|
||||||
```
|
|
||||||
|
|
||||||
You can develop a specific package by using a [filter](https://turborepo.dev/docs/crafting-your-repository/running-tasks#using-filters):
|
|
||||||
|
|
||||||
With [global `turbo`](https://turborepo.dev/docs/getting-started/installation#global-installation) installed:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
turbo dev --filter=web
|
|
||||||
```
|
|
||||||
|
|
||||||
Without global `turbo`:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
npx turbo dev --filter=web
|
|
||||||
yarn exec turbo dev --filter=web
|
|
||||||
pnpm exec turbo dev --filter=web
|
|
||||||
```
|
|
||||||
|
|
||||||
### Remote Caching
|
|
||||||
|
|
||||||
> [!TIP]
|
|
||||||
> Vercel Remote Cache is free for all plans. Get started today at [vercel.com](https://vercel.com/signup?utm_source=remote-cache-sdk&utm_campaign=free_remote_cache).
|
|
||||||
|
|
||||||
Turborepo can use a technique known as [Remote Caching](https://turborepo.dev/docs/core-concepts/remote-caching) to share cache artifacts across machines, enabling you to share build caches with your team and CI/CD pipelines.
|
|
||||||
|
|
||||||
By default, Turborepo will cache locally. To enable Remote Caching you will need an account with Vercel. If you don't have an account you can [create one](https://vercel.com/signup?utm_source=turborepo-examples), then enter the following commands:
|
|
||||||
|
|
||||||
With [global `turbo`](https://turborepo.dev/docs/getting-started/installation#global-installation) installed (recommended):
|
|
||||||
|
|
||||||
```sh
|
|
||||||
cd my-turborepo
|
|
||||||
turbo login
|
|
||||||
```
|
|
||||||
|
|
||||||
Without global `turbo`, use your package manager:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
cd my-turborepo
|
|
||||||
npx turbo login
|
|
||||||
yarn exec turbo login
|
|
||||||
pnpm exec turbo login
|
|
||||||
```
|
|
||||||
|
|
||||||
This will authenticate the Turborepo CLI with your [Vercel account](https://vercel.com/docs/concepts/personal-accounts/overview).
|
|
||||||
|
|
||||||
Next, you can link your Turborepo to your Remote Cache by running the following command from the root of your Turborepo:
|
|
||||||
|
|
||||||
With [global `turbo`](https://turborepo.dev/docs/getting-started/installation#global-installation) installed:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
turbo link
|
|
||||||
```
|
|
||||||
|
|
||||||
Without global `turbo`:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
npx turbo link
|
|
||||||
yarn exec turbo link
|
|
||||||
pnpm exec turbo link
|
|
||||||
```
|
|
||||||
|
|
||||||
## Useful Links
|
|
||||||
|
|
||||||
Learn more about the power of Turborepo:
|
|
||||||
|
|
||||||
- [Tasks](https://turborepo.dev/docs/crafting-your-repository/running-tasks)
|
|
||||||
- [Caching](https://turborepo.dev/docs/crafting-your-repository/caching)
|
|
||||||
- [Remote Caching](https://turborepo.dev/docs/core-concepts/remote-caching)
|
|
||||||
- [Filtering](https://turborepo.dev/docs/crafting-your-repository/running-tasks#using-filters)
|
|
||||||
- [Configuration Options](https://turborepo.dev/docs/reference/configuration)
|
|
||||||
- [CLI Usage](https://turborepo.dev/docs/reference/command-line-reference)
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user