dan/itpdp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

add simple docs

Browse source
This commit is contained in:
Daniel Bulant 2026-05-01 20:41:30 +02:00
parent 21f859c480
commit 6c965b9065
No known key found for this signature in database
3 changed files with 46 additions and 232 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
README.md Normal file
View file

@ -0,0 +1,7 @@
# Quiz app + api
A simple music quiz app
See `api` and `web` folders for more specific info.
Requires bun.js for runtime and postgres, easiest way to set postgres up is to get Docker.

31
api/README.md
View file

@ -1,4 +1,4 @@
# web # API
To install dependencies: To install dependencies:
@ -9,7 +9,32 @@ bun install
To run: To run:
```bash ```bash
bun run index.ts bun run dev
``` ```
This project was created using `bun init` in bun v1.3.11. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime. Requires running Postgres and environment setup.
Create `.env` file (in this folder):
```sh
# Leave as is if using docker/default Postgres install
DATABASE_URL=postgres://postgres:postgres@localhost/postgres
BETTER_AUTH_URL=http://127.0.0.1:3000
# random secure secret; can be left as is for development/testing
BETTER_AUTH_SECRET=vGIwQFYm4kUPHOhFNt882IbFaWhLklke
# Create a spotify web app.
# Add http://127.0.0.1:3000/api/auth/callback/spotify as callback URL there
# Copy and paste Client ID and Client secret to the following places:
SPOTIFY_CLIENT_ID=
SPOTIFY_CLIENT_SECRET=
```
Important files for editing:
- `src/workflows/quiz.ts` has the main Quiz loop.
- Questions are generated in `src/party/` files.
- `src/workflows/sync.ts` gets data from spotify and saves into database
- `src/workflows/party-analysis.ts` generates analysis details of a given party, to be used for question generation
- `src/party-types.ts` contains type definitions of party data, shared with frontend

240
web/README.md
View file

@ -1,238 +1,20 @@
Welcome to your new TanStack Start app! # Web
# Getting Started A Tanstack start React web app, using Shadcn components.
To run this application: Install dependencies:
```sh
```bash
bun install bun install
bun --bun run dev
``` ```
# Building For Production Run locally:
```sh
To build this application for production: bun run dev
```bash
bun --bun run build
``` ```
## Testing By default connects to local backend (see `../api`)
This project uses [Vitest](https://vitest.dev/) for testing. You can run the tests with: Important files to update:
```bash - `src/routes/index.tsx` has main route details
bun --bun run test - `src/components/party.tsx` contains quiz-specific details (game view, etc)
```
## Styling
This project uses [Tailwind CSS](https://tailwindcss.com/) for styling.
### Removing Tailwind CSS
If you prefer not to use Tailwind CSS:
1. Remove the demo pages in `src/routes/demo/`
2. Replace the Tailwind import in `src/styles.css` with your own styles
3. Remove `tailwindcss()` from the plugins array in `vite.config.ts`
4. Uninstall the packages: `bun install @tailwindcss/vite tailwindcss -D`
## Linting & Formatting
This project uses [Biome](https://biomejs.dev/) for linting and formatting. The following scripts are available:
```bash
bun --bun run lint
bun --bun run format
bun --bun run check
```
## Setting up Better Auth
1. Generate and set the `BETTER_AUTH_SECRET` environment variable in your `.env.local`:
```bash
bunx --bun @better-auth/cli secret
```
2. Visit the [Better Auth documentation](https://www.better-auth.com) to unlock the full potential of authentication in your app.
### Adding a Database (Optional)
Better Auth can work in stateless mode, but to persist user data, add a database:
```typescript
// src/lib/auth.ts
import { betterAuth } from "better-auth";
import { Pool } from "pg";
export const auth = betterAuth({
database: new Pool({
connectionString: process.env.DATABASE_URL,
}),
// ... rest of config
});
```
Then run migrations:
```bash
bunx --bun @better-auth/cli migrate
```
## Routing
This project uses [TanStack Router](https://tanstack.com/router) with file-based routing. 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 you will need to import the `Link` component from `@tanstack/react-router`.
```tsx
import { Link } from "@tanstack/react-router";
```
Then anywhere in your JSX you can use it like so:
```tsx
<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](https://tanstack.com/router/v1/docs/framework/react/api/router/linkComponent).
### 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 the routes. The route content will appear in the JSX where you render `{children}` in the `shellComponent`.
Here is an example layout that includes a header:
```tsx
import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
export const Route = createRootRoute({
head: () => ({
meta: [
{ charSet: 'utf-8' },
{ name: 'viewport', content: 'width=device-width, initial-scale=1' },
{ title: 'My App' },
],
}),
shellComponent: ({ children }) => (
<html lang="en">
<head>
<HeadContent />
</head>
<body>
<header>
<nav>
<Link to="/">Home</Link>
<Link to="/about">About</Link>
</nav>
</header>
{children}
<Scripts />
</body>
</html>
),
})
```
More information on layouts can be found in the [Layouts documentation](https://tanstack.com/router/latest/docs/framework/react/guide/routing-concepts#layouts).
## Server Functions
TanStack Start provides server functions that allow you to write server-side code that seamlessly integrates with your client components.
```tsx
import { createServerFn } from '@tanstack/react-start'
const getServerTime = createServerFn({
method: 'GET',
}).handler(async () => {
return new Date().toISOString()
})
// Use in a component
function MyComponent() {
const [time, setTime] = useState('')
useEffect(() => {
getServerTime().then(setTime)
}, [])
return <div>Server time: {time}</div>
}
```
## API Routes
You can create API routes by using the `server` property in your route definitions:
```tsx
import { createFileRoute } from '@tanstack/react-router'
import { json } from '@tanstack/react-start'
export const Route = createFileRoute('/api/hello')({
server: {
handlers: {
GET: () => json({ message: 'Hello, World!' }),
},
},
})
```
## 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:
```tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/people')({
loader: async () => {
const response = await fetch('https://swapi.dev/api/people')
return response.json()
},
component: PeopleComponent,
})
function PeopleComponent() {
const data = Route.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](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#loader-parameters).
# 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](https://tanstack.com).
For TanStack Start specific documentation, visit [TanStack Start](https://tanstack.com/start).