Best Practices - Kleap Documentation

Follow these guidelines to build better apps faster.

Planning Your App

Start with a Clear Vision

Before opening Kleap:

Define your goal - What problem does this app solve?
List core features - What must it do? (Start with 3-5)
Sketch the flow - How will users navigate?
Identify data - What information needs storing?

Choose the Right Template

Templates give you a head start:

SaaS Template - User auth, dashboard, billing
Portfolio - Personal sites, portfolios
Landing Page - Marketing, product launches
E-commerce - Product sales, checkout

Or start blank if you have a unique idea.

Building Incrementally

Small Steps Win

Do this

Build one feature at a time, test it, then add the next

Not this

Try to build everything at once in one long prompt

Recommended Build Order

Layout

Header, footer, navigation structure

Pages

Create main pages with placeholder content

Components

Build reusable components (cards, forms, etc.)

Styling

Refine colors, typography, spacing

Content

Add real content; enable Kleap Database if you need saved data or logins

Functionality

Add interactions, forms, features

Polish

Responsive fixes, loading states, error handling

Code Organization

Let AI Follow Conventions

Kleap uses a standard Astro project structure:

src/pages/       → Pages and routes (.astro files)
src/components/   → Reusable components (.astro and .tsx)
src/layouts/     → Shared page layouts (Base.astro)
src/styles/      → global.css and styles
public/          → Static assets (images, fonts)

Don’t fight this structure. Let AI organize code appropriately.

Component Reusability

Ask for reusable components:

"Create a Card component that I can reuse across different
sections with customizable title, description, and icon"

Then reference them:

"Use the Card component to display the pricing tiers"

Styling Guidelines

Consistent Design

Establish design tokens early:

"Use these colors throughout the app:
- Primary: blue-600
- Secondary: gray-600
- Background: gray-50
- Accent: purple-500"

Mobile First

Always consider mobile:

"Make sure this section works well on mobile devices,
with stacked layout and appropriate text sizes"

Database Best Practices

Plan Your Schema

Before asking AI to create tables:

List what data you need
Define relationships
Consider what queries you’ll run

Enable Security

Always ask for per-user data access:

"Create a posts table and scope it so users can only
see and edit their own posts"

Performance Tips

Optimize Images

Kleap optimizes images for you — just use normal <img> tags or Astro’s asset handling. There’s no next/image component.

"Add these images with appropriate sizes, alt text,
and lazy loading"

Keep It Static

Astro renders static HTML by default. Only add interactivity where you actually need it, using React islands.

"Make this section a static component, and only make the
image carousel interactive"

Add Loading States

"Add a loading skeleton while the data is being fetched"

Testing Your App

Test as You Build

After each change:

Check the preview
Test on mobile view
Click through the flow
Look for errors in console

Test Edge Cases

Empty states (no data)
Error states (failed requests)
Loading states
Long content
Many items

Before Publishing

Checklist

Configuration & Secrets

Kleap sites are static, so any value baked into the site is public. Use Astro build-time config for non-secret values only:

"Move the public API base URL to a PUBLIC_ environment
variable and read it with import.meta.env.PUBLIC_API_URL"

Never put a real secret (a private API key, token, or password) in a static site — it ships to the browser. Secrets belong in an external backend or serverless function. For payments use Stripe payment links (publishable key only); for form emails use built-in Forms.

Common Mistakes to Avoid

Building too much at once

Break large features into smaller prompts. Test after each change.

Ignoring mobile

Always test mobile view. Many users browse on phones.

Hardcoding data

Use database or props instead of hardcoded content for dynamic data.

Skipping error handling

Always handle what happens when things fail (no data, API errors).

Not using templates

Templates save hours of work. Start with one when possible.

Getting Help

When stuck:

Check the docs - Answer might be here
Ask AI to explain - “Why isn’t this working?”
Use version history - Roll back if needed
Join Discord - Community can help

Troubleshooting

Solutions to common problems

​Planning Your App

​Start with a Clear Vision

​Choose the Right Template

​Building Incrementally

​Small Steps Win

Do this

Not this

​Recommended Build Order

​Code Organization

​Let AI Follow Conventions

​Component Reusability

​Styling Guidelines

​Consistent Design

​Mobile First

​Database Best Practices

​Plan Your Schema

​Enable Security

​Performance Tips

​Optimize Images

​Keep It Static

​Add Loading States

​Testing Your App

​Test as You Build

​Test Edge Cases

​Before Publishing

​Checklist

​Configuration & Secrets

​Common Mistakes to Avoid

​Getting Help