# create-glstack

Scaffold a fullstack application with a Go backend, PostgreSQL database, and your choice of web and mobile frontends, connected via Connect RPC.

Supported web frontends:

- [SvelteKit](https://kit.svelte.dev/)
- [Solid Start](https://start.solidjs.com/)

Supported mobile frontends:

- [React Native + Expo](https://expo.dev/)

## Usage

```sh
bun create glstack
```

The CLI asks for:

- **Project name** -- used for the directory, the database and the `@<name>/rpc` package
- **Web frontend** -- SvelteKit, Solid Start or none
- **Mobile frontend** -- React Native + Expo or none
- **Bundle identifier** (Expo only) -- reverse-DNS id used as both the iOS bundle identifier and the Android package, e.g. `com.example.app`
- **Go package prefix** -- e.g. `github.com/you`, giving the module path `github.com/you/<name>`
- **Install dependencies** -- runs `bun install` in the new project

## What you get

A monorepo with the following structure:

- **`services/api`** -- Go backend using [Cobra](https://github.com/spf13/cobra) for CLI, [pgx](https://github.com/jackc/pgx) for Postgres, and [Connect RPC](https://connectrpc.com/) for the API layer
- **`apps/web`** -- Web frontend app (SvelteKit or Solid Start)
- **`apps/mobile`** -- Optional [React Native + Expo](https://expo.dev/) mobile app sharing the same RPC client
- **`packages/proto`** -- Protobuf service definitions with [Buf](https://buf.build/) for codegen (Go + TypeScript)
- **`packages/rpc`** -- Generated TypeScript Connect RPC client shared across frontend apps
- **`scripts`** -- Codegen helpers, e.g. building the `packages/rpc` index from the generated client

### Dev environment

The template includes a [devenv.nix](https://devenv.sh/) configuration for macOS and Linux that sets up:

- Go, TypeScript, Bun, Node.js
- PostgreSQL with an auto-provisioned database
- File watchers for protobuf, SQL, and frontend hot reload with proper process dependency ordering
- [Air](https://github.com/air-verse/air) for Go live reload
- [sqlc](https://sqlc.dev/) for type-safe SQL
- [dbmate](https://github.com/amacneil/dbmate) for database migrations
- With Expo: the Android SDK and an emulator, plus the iOS simulator on macOS

Start everything with:

```sh
cd <name>
devenv up
```

### Mobile (Expo)

`devenv up` creates an Android emulator matching your CPU (arm64 or x86_64), waits for it to boot and runs the app on it. On macOS it also builds and runs the app on the iOS simulator. Both apps share one Metro bundler, so saving a file reloads both.

The Android emulator reaches the API at `10.0.2.2:8080` and the iOS simulator at `127.0.0.1:8080`; the app picks the right one per platform.

The native `ios/` and `android/` folders are generated from `app.json` and not committed. After changing native config or upgrading Expo, delete them and they are regenerated on the next run.

#### iOS on macOS

Nix can't provide Xcode, so the iOS simulator needs a few things installed on the Mac. Entering the devenv shell checks them and lists anything missing; run `ios-check` to check again. Until they are met, `devenv up` skips iOS and runs everything else.

| Requirement | How to fix |
| --- | --- |
| Xcode | Install it from the [App Store](https://apps.apple.com/app/xcode/id497799835) |
| Xcode license and first-launch setup | `sudo xcodebuild -runFirstLaunch` |
| An iOS simulator runtime | `xcodebuild -downloadPlatform iOS` |
| An iPhone simulator | Create one in Xcode › Window › Devices and Simulators |

CocoaPods comes from Nix. The iOS build uses `/Applications/Xcode.app` (or the Xcode chosen with `xcode-select`) outside the Nix compiler environment, so the Command Line Tools being selected is fine.

### Starter example

The generated project includes a working Todo CRUD example wired end-to-end: protobuf schema, Go service implementation, SQL queries, and frontend UI. In the mobile app, rows animate into place with [Reanimated](https://docs.swmansion.com/react-native-reanimated/) when a todo is checked off and the list re-sorts.

## License

MIT