Best Practices

Tips and recommendations for building robust Spry applications

Project Organization

Keep Spryfile.md focused: Break large files into multiple partials
Group related tasks: Use Markdown headings to organize tasks logically
Use meaningful names: Give tasks descriptive names like setup-db instead of task1

Task Dependencies

# ✅ Good: Clear, flat structure
```bash setup-db
sqlite3 app.db < schema.sql
```

```bash seed-db --dep setup-db
sqlite3 app.db < seed.sql
```

# ❌ Avoid: Deep nesting
```bash task1
echo "step 1"
```
```bash task2 --dep task1
echo "step 2"
```
```bash task3 --dep task2
echo "step 3"
```
```bash task4 --dep task3
echo "step 4"
```

SQLPage Routes

Use descriptive filenames: user-profile.sql instead of page1.sql.
Prefix partials with underscore: _header.sql, _footer.sql.
Add authentication checks: Using partials to inject auth logic into your routes.

Development Workflow

1. Start with Watch Mode

Use --watch during development for instant feedback:

./spry.ts spc --fs dev-src.auto --watch

2. Test Incrementally

Test individual tasks before running the entire runbook:

./spry.ts task setup-db

3. Version Control

Commit your Spryfile.md and ignore generated files (dev-src.auto/, *.db).

Performance

Use indexes: Adding database indexes for frequently queried columns
Limit result sets: Always using LIMIT for large tables
Cache expensive queries Use SQLPage’s caching features

Security

Use parameterized queries: ever concatenate user input into SQL
Implement authentication: Check user sessions on protected routes
Use HTTPS: Always use HTTPS in production
Validate file uploads: Check file types and sizes

Documentation

Your Spryfile.md IS documentation. Make it readable:

## Database Setup

This section creates and seeds the application database.

```bash setup-db --descr "Initialize SQLite database with schema"
rm -f app.db
sqlite3 app.db < schema.sql
```

```bash seed-db --dep setup-db --descr "Populate database with initial data"
sqlite3 app.db < seed.sql
```

## Notes

- Database is recreated on each setup
- Seed data includes admin user (username: admin, password: changeme)