# 🚀 Hackathon Starter

A React starter built with Vite, TypeScript, and Tailwind CSS v4 for hackathons and rapid prototyping.

## What this project is (and is not)

Today this hackathon starter offers you an easy starting point to write some frontend JS code that can interact with staging data via the staging API. This API is the same API our staging frontend uses.

This definitely doesn't offer all the conveniences of our full frontend UI app. You don't get UI components or the ability to iterate/tweak the existing suno.com UI. If you want that you should work from the glockenspiel repo.

However, this project also doesn't come with the baggage and complexity of glockenspiel for prototyping new experiences.

### Practical Usage

This project is optimized to work with Claude Code via a `CLAUDE.md` file. 
You can use Claude Code within Cursor (if you launch `claude` from the Cursor terminal or from the terminal.
If you use the built-in Cursor agent, it won't automatically understand CLAUDE.md, so you should manually pass this as helpful context to the agent, especially around implementing generation-based flows.

Today Claude Code can generally get something that works to call many API endpoints, but lacks the application context and documentation to have complex flows work automatically.

For anything sufficiently complicated or specific (especially generating songs using specific model tasks), it is generally recommended to inspect the real web requests our app makes (via the developer console's network requests tab) to `studio-api-staging.suno.com` for something you might want to do and send that to Claude as a reference point.

## ✨ FE Features

- **React 19** with TypeScript for type safety
- **Vite** for fast development and building
- **Tailwind CSS v4** for rapid styling
- **TanStack Query** for server state management
- **OpenAPI** integration for type-safe API calls
- **ESLint** for code quality
- **Hot Module Replacement (HMR)** for instant updates

## 🚀 Quick Start

### Prerequisites

- [Node.js](https://nodejs.org/en/download)
- [yarn](https://yarnpkg.com/getting-started/install)

### Installation

1. Clone or download this repository -- [GitHub Desktop](https://github.com/apps/desktop) is probably the easiest way to get started here.
2. To make API calls to staging (this will use your actual staging account!)
   - Get a user token from [this retool link](https://retool.suno.com/apps/a13253bc-6407-11f0-8719-87f18ba42ff4/Usertoken%20Staging)
   - rename `.env.copy` -> `.env.local`, and add this token as the `VITE_API_USER_TOKEN`
3. Install dependencies:

   ```bash
   yarn install
   ```

4. Start the development server:

   ```bash
   yarn dev
   ```

5. Open your browser and visit `http://localhost:5173`
6. You should be able to see your staging handle & total clip count from staging on the main page!
7. Check out `docs/api-endpoints.md` for some ideas of APIs you can use for your FE and start prompting.

## 📁 Project Structure

```
hackathon-starter/
├── public/              # Static assets
├── src/
│   ├── App.tsx          # Main app component (TypeScript)
│   ├── main.tsx         # App entry point (TypeScript)
│   ├── index.css        # Tailwind imports
│   ├── assets/          # Static assets
│   └── utils/
│       ├── apiClient.ts # OpenAPI client setup
│       └── gen.ts       # Generated API types
├── index.html           # HTML template
├── package.json         # Dependencies
├── tailwind.config.js   # Tailwind v4 configuration
├── tailwind.colors.ts   # Custom color definitions
├── theme.css           # Theme styles
├── colors.css          # Color definitions
├── eslint.config.js    # ESLint configuration
├── vite.config.js      # Vite configuration
└── yarn.lock           # Yarn lock file
```

## 🎨 Styling

This starter uses **Tailwind CSS v4** for styling. You can:

- Use Tailwind utility classes directly in your TSX files
  - This shares some of the semantic colors used in the main repo (eg. text-background-primary)
- Customize colors in `tailwind.colors.ts`
- Modify theme styles in `theme.css`
- Add custom colors in `colors.css`
- Configure Tailwind in `tailwind.config.js`

## 🛠️ Available Scripts

- `yarn dev` - Start development server
- `yarn build` - Build for production
- `yarn preview` - Preview production build
- `yarn lint` - Run ESLint
- `yarn docs:generate` - Generate API endpoint documentation

## 🌐 API Integration

The starter includes OpenAPI integration for type-safe API calls:

- `src/utils/apiClient.ts` - OpenAPI client setup
- `src/utils/gen.ts` - Generated API types
- Uses `openapi-fetch` for lightweight API calls
- Integrated with **TanStack Query** for server state management

### 📚 API Documentation

The project includes comprehensive API endpoint documentation extracted from the OpenAPI specification:

#### Generate Documentation

```bash
yarn docs:generate
```

This command creates:

- `docs/api-endpoints.md` - Human-readable Markdown documentation
- `docs/api-endpoints.json` - Machine-readable JSON format

#### Documentation Features

- **Descriptions** extracted from OpenAPI comments
- **Organized by category**: Billing, Generation, Clips, Profiles, Video, and more
- **Table of contents** with direct links to each section

#### Usage in Code

Use the generated documentation to understand available endpoints, then call them using the type-safe client:

````typescript
import { useApiClient } from './utils/apiClient'

function MyComponent() {
  const client = useApiClient()

  // Example: Get user's billing info (from docs)
  const { data } = useQuery({
    queryKey: ['billing-info'],
    queryFn: () => client.GET('/api/billing/info')
  })
}

## 🔧 Customization

### Adding New Components

Create new component files in the `src/` directory and import them in `App.tsx`.

### Modifying Styles

- Edit `src/App.tsx` to change the layout and Tailwind classes
- Customize colors in `tailwind.colors.ts`
- Add theme styles in `theme.css`
- Modify `tailwind.config.js` to customize the design system

### Adding Dependencies

```bash
yarn add <package-name>
````

## 🚀 Deployment

### Development Server

```bash
yarn dev
```

### Production Build

```bash
yarn build
yarn preview
```

## 💡 Tips for Hackathons

1. **Start with the basics**: Use the existing layout as a foundation
2. **Leverage TypeScript**: Get type safety and better developer experience
3. **Use Tailwind CSS v4**: Rapid prototyping with utility classes
4. **Component organization**: Keep components in separate files as your project grows
5. **API integration**: Use the OpenAPI setup for type-safe API calls
6. **State management**: TanStack Query handles server state efficiently
7. **Use the console**: Check browser dev tools for debugging
8. **Hot reload**: Changes appear instantly - no need to refresh

## 🔧 Tech Stack

- **Frontend**: React 19, TypeScript, Vite
- **Styling**: Tailwind CSS v4
- **State Management**: TanStack Query
- **API**: OpenAPI with type-safe client
- **Linting**: ESLint
- **Package Manager**: Yarn

---

Built with ❤️ for hackathon success!