diff --git a/README.md b/README.md index 3f32465..2933d47 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,145 @@ -# React Native Todos +# Amplication Sample Mobile App -Welcome to this tutorial on how to build a full-stack mobile application with Amplication. +This repository contains a **full-stack Todo application** generated with [Amplication](https://amplication.com/) and extended with a **React Native (Expo)** mobile client. -This guide assumes that you have, at minimum, a working understanding of the following: +It is intended to serve as a _reference implementation_ that shows how you can combine Amplication’s auto-generated backend and Admin UI with a custom mobile application. -- [React Native](https://reactnative.dev/) -- [Expo](https://expo.dev/) -- [Node](https://nodejs.org/) -- [GitHub](https://github.com/) -- An IDE +--- -As well as having, at minimum, a basic understanding of the following: +## Repository structure -- REST APIs -- [GraphQL](https://graphql.org/) -- [Docker](https://www.docker.com/) +``` +├── admin-ui # React-Admin web application generated by Amplication +├── client # React Native (Expo) mobile application (todos list) +├── server # NestJS + Prisma backend generated by Amplication +└── README.md # ← you are here +``` -You'll also need an Amplication account, [visit here](https://app.amplication.com/login) to create one. +Each sub-project is an independent Node workspace with its own `package.json`, scripts and README containing additional details. +The high-level instructions below show the quickest way to get everything running together. -What we will do is go step by step to create a `Todos` application using React Native for your frontend and Amplication for your backend. +--- +## Prerequisites -https://user-images.githubusercontent.com/74011196/222221154-93f269ee-1442-4c28-b4fc-368415f6fe40.mp4 +1. **Node.js v16** (or newer) & **npm**/ **yarn** – used by all three projects. +2. **Docker Desktop** (or Docker Engine + Docker Compose) – required for the Postgres database used by the backend. +3. **Expo CLI** *(for the mobile app)* – install globally if you don’t have it: + ```bash + npm install -g expo-cli + ``` +> ℹ️ If you only want to run a single part (e.g. just the backend) jump into the corresponding folder and follow its local README. -If you get stuck, have any questions, or just want to say hi to other Amplication developers like yourself, then you should join our [Discord](https://discord.com/invite/KSJCZ24vj2)! +--- + +## Quick start (all services) + +The steps below spin up the database, backend API, Admin UI and the mobile app in development mode. + +```bash +# 1. Clone and enter the repo +$ git clone https://github.com/amplication/sample-mobile-app.git +$ cd sample-mobile-app + +# 2. Install dependencies for all workspaces +$ npm install --workspaces +# or run the three installs manually: +# (cd server && npm install) +# (cd admin-ui && npm install) +# (cd client && npm install) + +# 3. Start the Postgres database in Docker (runs detached) +$ cd server && npm run docker:db && cd .. + +# 4. Generate Prisma client & run migrations + seed data +$ cd server && npm run prisma:generate && npm run db:init && cd .. + +# 5. Start the backend API (GraphQL + REST running on http://localhost:3000) +$ cd server && npm start +``` +Open a **new terminal** window/tab for the next commands and keep the backend running. + +```bash +# 6. Start the Admin UI (http://localhost:3001) +$ cd admin-ui +$ npm start +``` + +```bash +# 7. Run the React Native mobile app +$ cd client +# Install iOS/Android/Web dependencies if you did not use the workspace install +$ npm install + +# Start the Expo dev server (choose one of the targets) +$ npm run android # → launches Android emulator / connected device +$ npm run ios # → launches iOS simulator (macOS only) +$ npm run web # → launches web version in browser +# or simply +$ npm start +``` + +Once the Metro bundler is up you can scan the QR code with the Expo Go app or run the simulator to interact with the mobile app. + +--- + +## Environment variables + +Most defaults work out-of-the-box for local development. +If you need to customise the backend connection (database credentials, JWT secret, etc.) copy `server/.env` and adapt the values: + +```bash +cp server/.env.example server/.env +``` + +Key variables you may want to change: + +| Variable | Purpose | Default | +| -------- | ------- | ------- | +| `SERVER_PORT` | HTTP port of the NestJS API | `3000` | +| `DB_URL` | Postgres connection string | `postgresql://admin:admin@localhost:5432/app` | +| `JWT_SECRET_KEY` | Secret used to sign auth tokens | `Change_ME!!!` | + +> Consult each sub-project’s README for the complete list. + +--- + +## Docker Compose (backend only) + +If you prefer running the backend and database together you can rely on Docker Compose: + +```bash +cd server +npm run compose:up # spins up the API (port 3000) and Postgres (port 5432) +``` + +Stop & clean: + +```bash +npm run compose:down +``` + +--- + +## Production builds + +* **Backend** – `cd server && npm run build` then create a Docker image with `npm run docker:build`. +* **Admin UI** – `cd admin-ui && npm run build` produces a static bundle in `admin-ui/build` (see React documentation for deployment options). +* **Mobile app** – Follow the [Expo build documentation](https://docs.expo.dev/build/introduction/) to generate production binaries. + +--- + +## Useful links + +* Amplication: https://amplication.com +* Amplication Discord: https://discord.com/invite/KSJCZ24vj2 +* React Native / Expo docs: https://docs.expo.dev/ +* NestJS docs: https://docs.nestjs.com/ +* Prisma docs: https://www.prisma.io/docs/ + +--- + +## License + +The contents of this repository are provided "as-is" for educational purposes. Refer to individual packages for their respective licenses.