Trey

Open Source Library Comparison & Discovery Platform

🇰🇷 한국어

📦 Development Environment Setup

This project uses mise to manage development tool versions.

Install mise (one-time setup)

curl https://mise.run | sh
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc

Project Setup

# Navigate to project folder (tool versions are applied automatically)
cd trey

# Install tools (one-time setup)
mise install

# Check currently active tools
mise current

Tool Versions

Tool	Version
Node.js	20
Bun	latest

🔐 Environment Variables

Copy .env.example to .env and configure the required values:

cp .env.example .env

Variable	Required	Description
NEXT_PUBLIC_SUPABASE_URL	✅	Supabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	✅	Supabase anonymous key
SUPABASE_SERVICE_ROLE_KEY	⚡	Supabase service role key (for admin operations)
GITHUB_TOKEN	⚡	GitHub API token (increases rate limit to 5000/hr)
ANTHROPIC_API_KEY	⚡	Anthropic API key for Claude AI content generation

⚡ Required for production deployment and AI features

🚀 Getting Started

# Install dependencies
bun install

# Start development server
mise run dev
# or
bun run dev

📋 Available Commands

Command	Description
mise run dev	Start development server
mise run build	Production build
mise run test	Run tests
mise run lint	Lint check
mise run format	Code formatting
mise run typecheck	TypeScript type check
mise run check	Lint + format combined check
mise run validate	Full validation (typecheck + lint + test)

💡 All commands can also be run using bun run <script> format.

🪝 Git Hooks

This project uses Husky and lint-staged for automatic code quality checks.

Pre-commit

Automatically runs lint and format checks on staged files:

• *.ts, *.tsx, *.js, *.jsx → Biome lint + format check with auto-fix
• *.json, *.css, *.md → Biome format check with auto-fix

Pre-push

Runs full project validation before push:

1. TypeScript type check
2. Lint check
3. Test execution

Push is blocked if any check fails.

🔄 CI/CD

GitHub Actions automatically runs CI pipeline on push or PR to main, dev, epic/** branches.

🔍 Lint & Format  ──┐
📘 TypeScript     ──┼──→ 🏗️ Build
🧪 Test           ──┘

Job	Description
Lint & Format	Biome lint/format check
TypeScript	Type check (tsc --noEmit)
Test	Vitest test execution
Build	Production build after all checks pass

Workflow file: .github/workflows/ci.yml

Trust Metrics Sync (Cron Job)

GitHub Actions automatically syncs trust metrics (GitHub stars, npm downloads) daily at 00:00 UTC (09:00 KST).

Required GitHub Secrets:

Secret	Description
SITE_URL	Production site URL (e.g., https://your-site.netlify.app)
CRON_SECRET	Secret key for API authentication

You can also trigger the sync manually from the Actions tab.

Workflow file: .github/workflows/sync-metrics.yml

Library Auto-Discovery (Weekly)

GitHub Actions automatically discovers new popular libraries weekly (Mondays at 09:00 UTC / 18:00 KST).

Scripts:

# Discover new libraries (dry-run mode)
bun run scripts/discover-libraries.ts --dry-run

# Discover and save to database
bun run scripts/discover-libraries.ts --limit 30

Options:

Flag	Description
--dry-run	Preview results without saving to DB
--github-only	Search only GitHub
--npm-only	Search only npm
--limit N	Maximum number of libraries (default: 30)
--min-stars N	Minimum GitHub stars (default: 5000)

Workflow file: .github/workflows/discover-libraries.yml

AI Content Generation (Manual/Webhook)

Generate AI-powered content summaries and playground code using Claude AI.

Scripts:

# Generate content for specific library
bun run scripts/generate-content.ts framer-motion

# Generate content for all libraries
bun run scripts/generate-content.ts --all

# Generate playground code
bun run scripts/generate-playground.ts --all

# Force regenerate (overwrites existing)
bun run scripts/generate-content.ts --all --force

AI Models Used:

Task	Model	Purpose
Content (Summary, Pros/Cons)	Claude 4.5 Sonnet	Balanced quality/cost
Playground Code	Claude 4.5 Opus	Best coding performance
Classification/Tagging	Claude 4.5 Haiku	Fast, low cost

Workflow file: .github/workflows/generate-content.yml

🏗️ Building For Production

mise run build
# or
bun run build

🧪 Testing

This project uses Vitest.

mise run test
# or
bun run test

🎨 Styling

This project uses Tailwind CSS for styling.

🛣️ Routing

This project uses TanStack Router. The initial setup is a file based router, which means routes are managed as files in src/routes.

Adding A Route

To add a new route to your application, just add a new file in the ./src/routes directory.

TanStack will automatically generate the content of the route file for you.

Now that you have two routes you can use a Link component to navigate between them.

Adding Links

To use SPA (Single Page Application) navigation, import the Link component from @tanstack/react-router.

import { Link } from "@tanstack/react-router";

Then anywhere in your JSX you can use it like so:

<Link to="/about">About</Link>

This will create a link that will navigate to the /about route.

More information on the Link component can be found in the Link documentation.

Using A Layout

In the File Based Routing setup, the layout is located in src/routes/__root.tsx. Anything you add to the root route will appear in all routes. The route content will appear in the JSX where you use the <Outlet /> component.

Here is an example layout that includes a header:

import { Outlet, createRootRoute } from "@tanstack/react-router";
import { TanStackRouterDevtools } from "@tanstack/react-router-devtools";

import { Link } from "@tanstack/react-router";

export const Route = createRootRoute({
  component: () => (
    <>
      <header>
        <nav>
          <Link to="/">Home</Link>
          <Link to="/about">About</Link>
        </nav>
      </header>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
});

The <TanStackRouterDevtools /> component is not required, so you can remove it if you don't want it in your layout.

More information on layouts can be found in the Layouts documentation.

📡 Data Fetching

There are multiple ways to fetch data in your application. You can use TanStack Query to fetch data from a server. But you can also use the loader functionality built into TanStack Router to load the data for a route before it's rendered.

For example:

const peopleRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "/people",
  loader: async () => {
    const response = await fetch("https://swapi.dev/api/people");
    return response.json() as Promise<{
      results: {
        name: string;
      }[];
    }>;
  },
  component: () => {
    const data = peopleRoute.useLoaderData();
    return (
      <ul>
        {data.results.map((person) => (
          <li key={person.name}>{person.name}</li>
        ))}
      </ul>
    );
  },
});

Loaders simplify your data fetching logic dramatically. Check out more information in the Loader documentation.

React-Query

React-Query is an excellent addition or alternative to route loading and integrating it into your application is a breeze.

First add your dependencies:

bun install @tanstack/react-query @tanstack/react-query-devtools

Next, create a query client and provider. We recommend putting those in main.tsx.

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// ...

const queryClient = new QueryClient();

// ...

if (!rootElement.innerHTML) {
  const root = ReactDOM.createRoot(rootElement);

  root.render(
    <QueryClientProvider client={queryClient}>
      <RouterProvider router={router} />
    </QueryClientProvider>
  );
}

You can also add TanStack Query Devtools to the root route (optional).

import { ReactQueryDevtools } from "@tanstack/react-query-devtools";

const rootRoute = createRootRoute({
  component: () => (
    <>
      <Outlet />
      <ReactQueryDevtools buttonPosition="top-right" />
      <TanStackRouterDevtools />
    </>
  ),
});

Now you can use useQuery to fetch your data.

import { useQuery } from "@tanstack/react-query";

import "./App.css";

function App() {
  const { data } = useQuery({
    queryKey: ["people"],
    queryFn: () =>
      fetch("https://swapi.dev/api/people")
        .then((res) => res.json())
        .then((data) => data.results as { name: string }[]),
    initialData: [],
  });

  return (
    <div>
      <ul>
        {data.map((person) => (
          <li key={person.name}>{person.name}</li>
        ))}
      </ul>
    </div>
  );
}

export default App;

You can find out everything you need to know on how to use React-Query in the React-Query documentation.

🗃️ State Management

Another common requirement for React applications is state management. There are many options for state management in React. TanStack Store provides a great starting point for your project.

First you need to add TanStack Store as a dependency:

bun install @tanstack/store

Now let's create a simple counter in the src/App.tsx file as a demonstration.

import { useStore } from "@tanstack/react-store";
import { Store } from "@tanstack/store";
import "./App.css";

const countStore = new Store(0);

function App() {
  const count = useStore(countStore);
  return (
    <div>
      <button onClick={() => countStore.setState((n) => n + 1)}>
        Increment - {count}
      </button>
    </div>
  );
}

export default App;

One of the many nice features of TanStack Store is the ability to derive state from other state. That derived state will update when the base state updates.

Let's check this out by doubling the count using derived state.

import { useStore } from "@tanstack/react-store";
import { Store, Derived } from "@tanstack/store";
import "./App.css";

const countStore = new Store(0);

const doubledStore = new Derived({
  fn: () => countStore.state * 2,
  deps: [countStore],
});
doubledStore.mount();

function App() {
  const count = useStore(countStore);
  const doubledCount = useStore(doubledStore);

  return (
    <div>
      <button onClick={() => countStore.setState((n) => n + 1)}>
        Increment - {count}
      </button>
      <div>Doubled - {doubledCount}</div>
    </div>
  );
}

export default App;

We use the Derived class to create a new store that is derived from another store. The Derived class has a mount method that will start the derived store updating.

Once we've created the derived store we can use it in the App component just like we would any other store using the useStore hook.

You can find out everything you need to know on how to use TanStack Store in the TanStack Store documentation.

📁 Demo Files

Files prefixed with demo can be safely deleted. They are there to provide a starting point for you to play around with the features you've installed.

📚 Learn More

You can learn more about all of the offerings from TanStack in the TanStack documentation.