{"id":13880695,"url":"https://github.com/PhilDL/remix-gospel-stack","last_synced_at":"2025-07-16T17:30:52.075Z","repository":{"id":59016077,"uuid":"533426847","full_name":"PhilDL/remix-gospel-stack","owner":"PhilDL","description":"Remix monorepo template with pnpm, TypeScript and Turborepo. The remix app deploys to fly.io or build to Docker image. Example packages for Database with Prisma, UI,  and internal TypeScript packages.","archived":false,"fork":false,"pushed_at":"2025-06-29T08:07:07.000Z","size":7370,"stargazers_count":226,"open_issues_count":14,"forks_count":14,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-29T09:19:56.574Z","etag":null,"topics":["docker","nextjs","prisma","remix-run","remix-stack","shadcn-ui","turborepo","typescript"],"latest_commit_sha":null,"homepage":"https://remix-gospel-stack.fly.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PhilDL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-09-06T17:12:42.000Z","updated_at":"2025-04-26T03:03:26.000Z","dependencies_parsed_at":"2023-02-18T07:01:11.683Z","dependency_job_id":"fe11b212-f0e8-4498-a42f-b02ae228f3a2","html_url":"https://github.com/PhilDL/remix-gospel-stack","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/PhilDL/remix-gospel-stack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilDL%2Fremix-gospel-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilDL%2Fremix-gospel-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilDL%2Fremix-gospel-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilDL%2Fremix-gospel-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PhilDL","download_url":"https://codeload.github.com/PhilDL/remix-gospel-stack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilDL%2Fremix-gospel-stack/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265527543,"owners_count":23782480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","nextjs","prisma","remix-run","remix-stack","shadcn-ui","turborepo","typescript"],"created_at":"2024-08-06T08:03:24.276Z","updated_at":"2025-07-16T17:30:52.069Z","avatar_url":"https://github.com/PhilDL.png","language":"TypeScript","funding_links":[],"categories":["Boilerplates \u0026 Starters","TypeScript"],"sub_categories":[],"readme":"# Remix Gospel stack with Turborepo\n\n![The Remix Gospel Stack](https://repository-images.githubusercontent.com/533426847/134e6276-a6a8-41f1-94d3-f6dcb8f58b5f)\n\nRemix TypeScript monorepo with Turborepo pipelines, Prisma, PostgreSQL OR SQLite (Litefs), Docker deploy to Fly.io, pnpm, shadcn/ui TailwindCSS.\n\n### Quickstart (recommended)\n\n```bash\npnpm create remix@latest --init-script --install --template https://github.com/PhilDL/remix-gospel-stack\n```\n\n\u003e :minidisc: This repository is opiniated:\n\u003e\n\u003e - **TypeScript** only.\n\u003e - Only compatible with **pnpm** package manager to handle monorepo workspaces.\n\u003e - Uses turborepo pipelines + cache to build, lint, typecheck, and test the monorepo.\n\n### (Alternative) Cloning the repository\n\n```bash\ngit clone git@github.com:PhilDL/remix-gospel-stack.git\ncd remix-gospel-stack\npnpm add -w @remix-run/dev\npnpm remix init\n```\n\n## What's in the stack\n\nThis stack is a Remix oriented Monorepo powered by turborepo and [pnpm workspaces](https://pnpm.io/workspaces). Containing a ready-to-deploy Remix App on [fly.io](https://fly.io) via the building of a Docker container.\n\n_This Package **uses `pnpm` as the package manager** of choice to manage workspaces. It may work with `yarn` and `npm` if you put the workspace definitions in the package.json file but there is no guarantee._\n\n### Monorepo architecture powered by [Turborepo](https://turborepo.org/) and pnpm workspaces:\n\n- `apps` Folder containing the applications\n  - [`remix-app`](https://github.com/PhilDL/remix-gospel-stack/tree/main/apps/remix-app): the [Remix.run](https://remix.run) app in ESM.\n  - [`remix-vercel`](https://github.com/PhilDL/remix-gospel-stack/tree/main/apps/remix-vercel): the [Remix.run](https://remix.run) app, ready to be deployed on [Vercel](https://vercel.com).\n  - [`nextjs-app`](https://github.com/PhilDL/remix-gospel-stack/tree/main/apps/nextjs-app): a [Next.js](https://nextjs.org) app\n- `packages` Folder containing examples\n\n  - [`ui`](https://github.com/PhilDL/remix-gospel-stack/tree/main/packages/ui): a React UI package example powered by [shadcn/ui](https://ui.shadcn.com/). Some example components and shadcn/ui Tailwind config exported as Tailwind plugin and preset.\n  - [`database`](https://github.com/PhilDL/remix-gospel-stack/tree/main/packages/database): a [Prisma](https://prisma.io) wrapper ready to be used in other packages, or apps. Bundled with [tsup](https://tsup.egoist.dev/). Can be PostgreSQL or SQLite // Litefs dependening of what you choose during installation.\n  - [`business`](https://github.com/PhilDL/remix-gospel-stack/tree/main/packages/business): an example package using the Prisma `database` as a dependency and using a _repository pattern_ like example.\n  - [`internal-nobuild`](https://github.com/PhilDL/remix-gospel-stack/tree/main/packages/internal-nobuild): an example package that is pure TypeScript with no build steps. The `main` entrypoint to the package is directly `src/index.ts`. Remix takes care of compiling with its own build step (with esbuild). This packages also contains unit test with Vitest.\n    Remix uses `tsconfig.json` paths to reference to that project and its types. _I would recommend these types of **internal** packages when you don't plan on publishing the package._\n\n- `config-packages`:\n  - Eslint packages with different preset configs.\n  - TS Configs, also with different presets.\n  - [Tailwind](https://tailwindcss.com/) configs.\n\n### All Remix future flags activated:\n\n```ts\nfuture: {\n  unstable_optimizeDeps: true,\n  v3_fetcherPersist: true,\n  v3_lazyRouteDiscovery: true,\n  v3_relativeSplatPath: true,\n  v3_throwAbortReason: true,\n  v3_singleFetch: true,\n  v3_routeConfig: true,\n},\n```\n\n### What else ?\n\n- Remix App [Multi-region Fly app deployment](https://fly.io/docs/reference/scaling/) with [Docker](https://www.docker.com/)\n- Database comes in 2 flavors that you choose at install:\n  - [Multi-region Fly PostgreSQL Cluster](https://fly.io/docs/getting-started/multi-region-databases/)\n  - [Litefs - Distributed SQLite](https://fly.io/docs/litefs/)\n- Remix App Healthcheck endpoint for [Fly backups region fallbacks](https://fly.io/docs/reference/configuration/#services-http_checks)\n- [GitHub Actions](https://github.com/features/actions) for deploy the Remix App on merge to production and staging environments.\n- End-to-end testing with [Playwright](https://github.com/microsoft/playwright) in the Remix App\n- Unit testing with [Vitest](https://vitest.dev) and [Testing Library](https://testing-library.com) inside the different packages.\n- Code formatting with [Prettier](https://prettier.io)\n- Static Types with [TypeScript](https://typescriptlang.org)\n\n\u003e **Warning**\n\u003e All the following commands should be launched from the **monorepo root directory**\n\n## Developement\n\n- Install the dependencies.\n  ```bash\n  pnpm install\n  ```\n  You also have to copy the example .env.example:\n  ```sh\n  cp .env.example .env\n  cp .env.example .env.docker\n  ```\n- Start the postgresql docker container\n\n  ```bash\n  pnpm run docker:db\n  ```\n\n  \u003e **Note:** The npm script will complete while Docker sets up the container in the background. Ensure that Docker has finished and your container is running before proceeding.\n\n- Generate prisma schema\n  ```bash\n  pnpm run generate\n  ```\n- Run the Prisma migration to the database\n  ```bash\n  pnpm run db:migrate:deploy\n  ```\n- Run the first build (with dependencies via the `...` option)\n  ```bash\n  pnpm run build --filter=@remix-gospel-stack/remix-app...\n  ```\n  **Running simply `pnpm run build` will build everything, including the NextJS app.**\n- Run the Remix dev server\n  ```bash\n  pnpm run dev --filter=@remix-gospel-stack/remix-app\n  ```\n\n## Switch between PostgreSQL and SQLite (Litefs)\n\n- To switch between PostgreSQL and SQLite (Litefs), there is a turbo generator you can use from the root of the repository.\n\n  ```bash\n  pnpm turbo gen scaffold-database\n  ```\n\n  Then follow the prompts. Be careful though, prisma migrations are linked to a specific database, so you will have to delete the `migrations` folder.\n\n  \u003e **Note:** You will have to run `pnpm i --fix-lockfile` again after switching to SQLite (Litefs) that require another package (litefs-js). You will probably also have to run `pnpm run setup` again to generate the first migration.\n\n## Create packages\n\n### Internal package\n\n```bash\nturbo gen workspace --name @remix-gospel-stack/foobarbaz --type package --copy\n```\n\nThen follow the prompts\n\n## Tests, Typechecks, Lint, Install packages...\n\nCheck the `turbo.json` file to see the available pipelines.\n\n- Run the Cypress tests and Dev\n  ```bash\n  pnpm run test:e2e:dev --filter=@remix-gospel-stack/remix-app\n  ```\n- Lint everything\n  ```bash\n  pnpm run lint\n  ```\n- Typecheck the whole monorepo\n  ```bash\n  pnpm run typecheck\n  ```\n- Test the whole monorepo\n  ```bash\n  pnpm run test\n  or\n  pnpm run test:dev\n  ```\n- How to install an npm package in the Remix app ?\n  ```bash\n  pnpm add dayjs --filter @remix-gospel-stack/remix-app\n  ```\n- Tweak the tsconfigs, eslint configs in the `config-package` folder. Any package or app will then extend from these configs.\n\n## Deployement on fly.io – PostgreSQL\n\n\u003e **Warning**\n\u003e All the following commands should be launched from the **monorepo root directory**\n\nPrior to your first deployment, you'll need to do a few things:\n\n- First singup the fly CLI\n  ```bash\n  fly auth signup\n  ```\n- Create two apps on Fly, one for staging and one for production:\n\n  ```sh\n  fly apps create remix-gospel-stack\n  fly apps create remix-gospel-stack-staging\n  ```\n\n  \u003e **Note:** Once you've successfully created an app, double-check the `fly.toml` file to ensure that the `app` key is the name of the production app you created. This Stack [automatically appends a unique suffix at init](https://github.com/remix-run/blues-stack/blob/4c2f1af416b539187beb8126dd16f6bc38f47639/remix.init/index.js#L29) which may not match the apps you created on Fly. You will likely see [404 errors in your Github Actions CI logs](https://community.fly.io/t/404-failure-with-deployment-with-remix-blues-stack/4526/3) if you have this mismatch.\n\n- Initialize Git.\n\n  ```sh\n  git init\n  ```\n\n- Create a new [GitHub Repository](https://repo.new), and then add it as the remote for your project. **Do not push your app yet!**\n\n  ```sh\n  git remote add origin \u003cORIGIN_URL\u003e\n  ```\n\n- Add a `FLY_API_TOKEN` to your GitHub repo. To do this, go to your user settings on Fly and create a new [token](https://web.fly.io/user/personal_access_tokens/new), then add it to [your repo secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) with the name `FLY_API_TOKEN`.\n\n- Create a database for both your staging and production environments:\n\nDatabase creation:\n\n```sh\nfly postgres create --name remix-gospel-stack-db\nfly postgres attach --app remix-gospel-stack remix-gospel-stack-db\n\nfly postgres create --name remix-gospel-stack-staging-db\nfly postgres attach --app remix-gospel-stack-staging remix-gospel-stack-staging-db\n```\n\n\u003e **Note:** You'll get the same warning for the same reason when attaching the staging database that you did in the `fly set secret` step above. No worries. Proceed!\n\nFly will take care of setting the `DATABASE_URL` secret for you.\n\n## Deployement on fly.io – SQLite Litefs\n\n\u003e **Warning**\n\u003e All the following commands should be launched from the **monorepo root directory**\n\nPrior to your first deployment, you'll need to do a few things:\n\n- First singup the fly CLI\n  ```bash\n  fly auth signup\n  ```\n- Create two apps on Fly, one for staging and one for production:\n\n  ```sh\n  fly apps create remix-gospel-stack\n  fly apps create remix-gospel-stack-staging\n  ```\n\n  \u003e **Note:** Once you've successfully created an app, double-check the `fly.toml` file to ensure that the `app` key is the name of the production app you created. This Stack [automatically appends a unique suffix at init](https://github.com/remix-run/blues-stack/blob/4c2f1af416b539187beb8126dd16f6bc38f47639/remix.init/index.js#L29) which may not match the apps you created on Fly. You will likely see [404 errors in your Github Actions CI logs](https://community.fly.io/t/404-failure-with-deployment-with-remix-blues-stack/4526/3) if you have this mismatch.\n\n- Initialize Git.\n\n  ```sh\n  git init\n  ```\n\n- Create a new [GitHub Repository](https://repo.new), and then add it as the remote for your project. **Do not push your app yet!**\n\n  ```sh\n  git remote add origin \u003cORIGIN_URL\u003e\n  ```\n\n- Add a `FLY_API_TOKEN` to your GitHub repo. To do this, go to your user settings on Fly and create a new [token](https://web.fly.io/user/personal_access_tokens/new), then add it to [your repo secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) with the name `FLY_API_TOKEN`.\n\nCreate a persistent volume for the sqlite database for both your staging and production environments. Run the following (feel free to change the GB size based on your needs and the region of your choice (https://fly.io/docs/reference/regions/). If you do change the region, make sure you change the primary_region in fly.toml as well):\n\n```sh\nfly volumes create data --region cdg --size 1 --app remix-gospel-stack\nfly volumes create data --region cdg --size 1 --app remix-gospel-stack-staging\n```\n\nThen attach the volumes to the apps:\n\n```sh\nfly consul attach --app remix-gospel-stack\nfly consul attach --app remix-gospel-stack-staging\n```\n\n#### Start coding!\n\nNow that everything is set up you can commit and push your changes to your repo. Every commit to your `main` branch will trigger a deployment to your production environment, and every commit to your `dev` branch will trigger a deployment to your staging environment.\n\nIf you run into any issues deploying to Fly, make sure you've followed all of the steps above and if you have, then post as many details about your deployment (including your app name) to [the Fly support community](https://community.fly.io). They're normally pretty responsive over there and hopefully can help resolve any of your deployment issues and questions.\n\n### Multi-region deploys\n\nOnce you have your site and database running in a single region, you can add more regions by following [Fly's Scaling](https://fly.io/docs/reference/scaling/) and [Multi-region PostgreSQL](https://fly.io/docs/getting-started/multi-region-databases/) docs.\n\nMake certain to set a `PRIMARY_REGION` environment variable for your app. You can use `[env]` config in the `fly.toml` to set that to the region you want to use as the primary region for both your app and database.\n\n#### Testing your app in other regions\n\nInstall the [ModHeader](https://modheader.com/) browser extension (or something similar) and use it to load your app with the header `fly-prefer-region` set to the region name you would like to test.\n\nYou can check the `x-fly-region` header on the response to know which region your request was handled by.\n\n## GitHub Actions\n\nWe use GitHub Actions for continuous integration and deployment. Anything that gets into the `main` branch will be deployed to production after running tests/build/etc. Anything in the `dev` branch will be deployed to staging.\n\n## Manually Build The Docker Image to deploy with Fly.io\n\n- Create a docker network\n  ```\n  docker network create app_network\n  ```\n- Build the docker image\n  ```sh\n  pnpm docker:build:remix-app\n  ```\n- Run the docker Image\n  ```sh\n  pnpm docker:run:remix-app\n  ```\n- (Optionnal) If you want to manually deploy to fly.io:\n  ```bash\n  DOCKER_DEFAULT_PLATFORM=linux/amd64 flyctl deploy --config ./apps/remix-app/fly.toml --dockerfile ./apps/remix-app/Dockerfile\n  ```\n\n## Useful Turborepo Links\n\nLearn more about the power of Turborepo:\n\n- [Pipelines](https://turborepo.org/docs/features/pipelines)\n- [Caching](https://turborepo.org/docs/features/caching)\n- [Remote Caching (Beta)](https://turborepo.org/docs/features/remote-caching)\n- [Scoped Tasks](https://turborepo.org/docs/features/scopes)\n- [Configuration Options](https://turborepo.org/docs/reference/configuration)\n- [CLI Usage](https://turborepo.org/docs/reference/command-line-reference)\n\n## Thanks\n\n- The ESM setup is heavily inspired by the [epic-stack](https://github.com/epicweb-dev/epic-stack) by [@kentcdodds](https://github.com/kentcdodds)\n- Thanks to [@shadcn](https://github.com/shadcn) for the amazing [component library](https://github.com/shadcn/ui).\n- The UI integration and some good practices were shamelessly borrowed from [@juliusmarminge](https://github.com/juliusmarminge) project [acme-corp monorepo](https://github.com/juliusmarminge/acme-corp)\n\n## Support\n\nIf you found the template useful, please consider giving it a [Star ⭐](https://github.com/PhilDL/remix-gospel-stack). Thanks you!\n\n## Disclaimer\n\nI am in no way an expert on Monorepo, Docker or CI. The setup proposed here is one of many and probably could be improved 10x, but I am learning by myself along the way, so if you see any possible improvement please submit a PR. I will appreciate it greatly !\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPhilDL%2Fremix-gospel-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPhilDL%2Fremix-gospel-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPhilDL%2Fremix-gospel-stack/lists"}