Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 86 additions & 45 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,73 +1,114 @@
# Welcome to your Lovable project
# madewithlovable

## Project info
A step-by-step guide to de-risking your [Lovable](https://lovable.dev) project for production use.

**URL**: https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID
Lovable is excellent for agility and speed-to-market, but shipping AI-generated code to production without guardrails introduces structural risks — from unreviewed changes breaking infrastructure to vendor lock-in on hosting. This project provides a repeatable playbook to mitigate those risks while keeping the benefits of rapid AI-assisted development.

## How can I edit this code?
- **Lovable-hosted:** [made-with.lovable.app](https://made-with.lovable.app)
- **Self-hosted (AWS):** [d12vini1os6dc2.cloudfront.net](https://d12vini1os6dc2.cloudfront.net)

There are several ways of editing your application.
---

**Use Lovable**
## What This Is

Simply visit the [Lovable Project](https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID) and start prompting.
An interactive wizard that walks you through six steps to establish ownership, safety, and operational independence over a Lovable-built application. Each step is optional (except the first), so you can adopt only what makes sense for your project.

Changes made via Lovable will be committed automatically to this repo.
---

**Use your preferred IDE**
## The Six Steps

If you want to work locally using your own IDE, you can clone this repo and push changes. Pushed changes will also be reflected in Lovable.
### 1. Project URL

The only requirement is having Node.js & npm installed - [install with nvm](https://github.com/nvm-sh/nvm#installing-and-updating)
Enter your Lovable project URL. The wizard extracts the project UUID and uses it to generate context-aware links throughout the remaining steps (e.g., direct links to your project's GitHub settings, Knowledge configuration, etc.).

Follow these steps:
### 2. Connect to GitHub

```sh
# Step 1: Clone the repository using the project's Git URL.
git clone <YOUR_GIT_URL>
Export your Lovable project to a GitHub repository. This is the foundation of everything else — without version control, you can't review changes, run CI/CD, or deploy independently. Lovable syncs commits bidirectionally, so you keep the AI editor workflow while gaining full Git history.

# Step 2: Navigate to the project directory.
cd <YOUR_PROJECT_NAME>
### 3. Guardrails

# Step 3: Install the necessary dependencies.
npm i
Add a `LOVABLE.md` file to your repository root that scopes what the AI is allowed to modify. This file acts as a contract: Lovable (and any other AI agent) should only touch application source code inside `src/`, frontend build configuration, and database migrations. Protected files include:

# Step 4: Start the development server with auto-reloading and an instant preview.
npm run dev
```
- Infrastructure (`Dockerfile`, `docker-compose.yml`, `terraform/`)
- CI/CD pipelines (`.github/`)
- The guardrails file itself (`LOVABLE.md`)

The guardrails are enforced in two ways:
1. **At authoring time** — by registering `LOVABLE.md` as custom knowledge in your Lovable project settings, so the AI respects the boundaries while generating code.
2. **At merge time** — by the CI/CD pipeline's automated review (see Step 6).

### 4. Local Development Setup

Run the full application locally using Docker, independent of Lovable's preview environment. This enables:

- Working in your preferred IDE or with other AI coding agents (Cursor, Claude Code, etc.)
- Offline development
- Running the test suite locally
- Building production artifacts

The setup is a single command: `docker-compose up`, which starts a development server on `localhost:8081` with hot-reloading and volume-mounted source code.

### 5. Production Self-Hosting

**Edit a file directly in GitHub**
Decouple your production environment from Lovable's hosting. The guide covers:

- Navigate to the desired file(s).
- Click the "Edit" button (pencil icon) at the top right of the file view.
- Make your changes and commit the changes.
- **Creating a `production` branch** in GitHub to separate what's deployed from what's being developed.
- **AWS S3 + CloudFront** as the hosting infrastructure (private S3 bucket as origin, CloudFront for delivery). Terraform configuration is provided, but manual setup via the AWS Console works too.
- **Building and deploying** — running `npm run build` (locally or via Docker) and uploading the `dist/` folder to S3.
- **Lovable Cloud (Supabase) considerations** — by default, self-hosted frontends share the same backend. For a dedicated production database, a manual migration to a managed Supabase instance is required.

**Use GitHub Codespaces**
**Key technical notes:**
- CloudFront must have `index.html` set as the Default root object.
- Lovable occasionally desyncs `package-lock.json` from `package.json`. If `npm ci` fails, use `npm install` and commit the updated lock file.

- Navigate to the main page of your repository.
- Click on the "Code" button (green button) near the top right.
- Select the "Codespaces" tab.
- Click on "New codespace" to launch a new Codespace environment.
- Edit files directly within the Codespace and commit and push your changes once you're done.
### 6. CI/CD Pipeline

## What technologies are used for this project?
Three GitHub Actions workflows automate the release process:

This project is built with:
| Workflow | Trigger | Purpose |
|---|---|---|
| `initiate-release.yml` | Manual (workflow_dispatch) | Creates a PR from `main` → `production` with an auto-generated changelog |
| `ci-guardrails.yml` | PR to `production` | Claude reviews the diff against `LOVABLE.md` guardrails — approves and merges if clean, requests changes if violations are found |
| `deploy.yml` | Push to `production` | Builds the app, syncs to S3, and invalidates the CloudFront cache |

- Vite
- TypeScript
- React
- shadcn-ui
- Tailwind CSS
**Required setup:**
- Install the [Claude GitHub app](https://github.com/apps/claude) on your repository
- Add the `ANTHROPIC_API_KEY` secret (from [Anthropic Console](https://console.anthropic.com/settings/keys))
- Add AWS IAM credentials as secrets (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) with permissions for S3 and CloudFront
- Add GitHub Actions **variables**: `S3_BUCKET` and `CLOUDFRONT_DISTRIBUTION_ID`
- If using Lovable Cloud: add `VITE_SUPABASE_URL` and `VITE_SUPABASE_PUBLISHABLE_KEY` as secrets
- Enable "Allow GitHub Actions to create and approve pull requests" in your organization/repository settings

## How can I deploy this project?
**The release flow:**
1. A non-technical user (or anyone) triggers the "Move main to production" workflow manually.
2. Claude generates a release PR with a summary of changes.
3. The guardrails workflow automatically reviews the PR diff — if all changes are within scope, it approves and merges. If guardrail violations are detected, it requests changes with inline comments.
4. On merge to `production`, the deploy workflow builds and publishes to AWS.

Simply open [Lovable](https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID) and click on Share -> Publish.
---

## Can I connect a custom domain to my Lovable project?
## Tech Stack

Yes, you can!
- [React](https://react.dev) + [TypeScript](https://www.typescriptlang.org)
- [Vite](https://vitejs.dev)
- [Tailwind CSS](https://tailwindcss.com) + [shadcn/ui](https://ui.shadcn.com)
- [Framer Motion](https://www.framer.com/motion/) for step transitions

To connect a domain, navigate to Project > Settings > Domains and click Connect Domain.
---

## Getting Started

```sh
git clone <YOUR_GIT_URL>
cd <YOUR_PROJECT_NAME>
npm install
npm run dev
```

Or with Docker:

```sh
docker-compose up
```

Read more here: [Setting up a custom domain](https://docs.lovable.dev/features/custom-domain#custom-domain)
The app will be available at `http://localhost:8081`.
19 changes: 16 additions & 3 deletions src/components/steps/StepProjectUrl.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,22 @@ export function StepProjectUrl() {
✓ Valid project detected
</p>
)}
<Button onClick={handleNext} disabled={!isValid} className="bg-accent text-accent-foreground hover:bg-accent/90">
Next <ArrowRight className="ml-2 h-4 w-4" />
</Button>
<div className="flex gap-3">
<Button onClick={handleNext} disabled={!isValid} className="bg-accent text-accent-foreground hover:bg-accent/90">
Next <ArrowRight className="ml-2 h-4 w-4" />
</Button>
<Button
variant="outline"
onClick={() => {
const dummyUrl = "https://lovable.dev/projects/00000000-0000-0000-0000-000000000000";
setUrl(dummyUrl);
setProjectUuid("00000000-0000-0000-0000-000000000000");
nextStep();
}}
>
Continue with demo project
</Button>
</div>
</div>
);
}