# 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** -- lowercase letters, digits and dashes; used for the directory, the database and the `@<name>/rpc` package. An existing non-empty directory is never overwritten
- **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` starts Metro as its own process, creates an Android emulator matching your CPU (arm64 or x86_64), waits up to 5 minutes 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 use the same Metro bundler, so saving a file reloads both, and one platform failing to build doesn't stop the other.

The app reaches the API at `127.0.0.1:8080` everywhere: the iOS simulator shares the Mac's network, and `devenv up` runs `adb reverse` for the emulator and any Android phone connected over USB. Physical iPhones aren't covered, since the API only listens on localhost.

The example apps poll the API every 2 seconds, so a change made on one device or in the web app shows up on the others.

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 (once they pass, at most once a day); run `ios-check` to check again. Until they are met, `devenv up` skips iOS and runs everything else. Set `SKIP_IOS_CHECK=1` to turn the check off, e.g. in `devenv.local.nix`.

| 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