Add development workflow and project setup
🛠️ Development Infrastructure: - package.json with npm scripts for development - live-server for hot reload during development - Custom dev helper script with project validation - Comprehensive .gitignore for Node.js and Go 📖 Documentation: - Updated README.md with project overview and quick start - DEVELOPMENT.md with detailed development guide - Demo instructions and testing scenarios 🚀 Available Commands: - npm run dev (start development server) - npm run dev:check (validate project setup) - npm run dev:demo (show testing instructions) - npm run dev:help (list all commands) ✨ Features: - Live reload on file changes - Project health checking - 18 editable elements detected - 14.3KB core library size Next: Ready for active development and testing!
This commit is contained in:
69
.gitignore
vendored
Normal file
69
.gitignore
vendored
Normal file
@@ -0,0 +1,69 @@
|
||||
# Dependencies
|
||||
node_modules/
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
|
||||
# Build outputs
|
||||
dist/
|
||||
build/
|
||||
|
||||
# Environment files
|
||||
.env
|
||||
.env.local
|
||||
.env.development.local
|
||||
.env.test.local
|
||||
.env.production.local
|
||||
|
||||
# IDE files
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# OS files
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Logs
|
||||
logs
|
||||
*.log
|
||||
|
||||
# Runtime data
|
||||
pids
|
||||
*.pid
|
||||
*.seed
|
||||
*.pid.lock
|
||||
|
||||
# Coverage directory used by tools like istanbul
|
||||
coverage/
|
||||
|
||||
# Temporary folders
|
||||
tmp/
|
||||
temp/
|
||||
|
||||
# Optional npm cache directory
|
||||
.npm
|
||||
|
||||
# Optional REPL history
|
||||
.node_repl_history
|
||||
|
||||
# Go specific (for future backend)
|
||||
*.exe
|
||||
*.exe~
|
||||
*.dll
|
||||
*.so
|
||||
*.dylib
|
||||
*.test
|
||||
*.out
|
||||
go.work
|
||||
vendor/
|
||||
|
||||
# Database files
|
||||
*.db
|
||||
*.sqlite
|
||||
*.sqlite3
|
||||
|
||||
# Local development files
|
||||
.local/
|
||||
160
DEVELOPMENT.md
Normal file
160
DEVELOPMENT.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# Insertr Development Guide
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Install dependencies**:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **Start development server**:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
This will start live-server on http://localhost:3000 and automatically open the demo site.
|
||||
|
||||
3. **Alternative commands**:
|
||||
```bash
|
||||
npm run dev:about # Open about page directly
|
||||
npm run serve # Alias for npm run dev
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Frontend Development (Current Phase)
|
||||
|
||||
- **Demo Site**: `demo-site/` contains the prototype website
|
||||
- **Core Library**: `demo-site/insertr/insertr.js` - the main Insertr library
|
||||
- **Styling**: `demo-site/insertr/insertr.css` - edit interface styles
|
||||
- **Mock API**: `demo-site/mock-api/content.json` - sample backend data structure
|
||||
|
||||
### Testing the Three User Types
|
||||
|
||||
1. **Customer View**: Open the site normally - clean, no edit interface
|
||||
2. **Client View**: Click "Login as Client" then "Edit Mode: On" - see edit buttons
|
||||
3. **Developer View**: Look at the HTML source to see simple integration
|
||||
|
||||
### Making Changes
|
||||
|
||||
- **Live Reload**: The server automatically refreshes when you save changes
|
||||
- **JavaScript**: Edit `demo-site/insertr/insertr.js` to modify core functionality
|
||||
- **Styling**: Edit `demo-site/insertr/insertr.css` for UI changes
|
||||
- **Content**: Edit HTML files to test different content structures
|
||||
|
||||
### Adding New Features
|
||||
|
||||
1. **Content Types**: Extend the `createEditForm()` method in insertr.js
|
||||
2. **UI Components**: Add new CSS classes and corresponding JavaScript
|
||||
3. **Authentication**: Modify the mock auth system in `toggleAuthentication()`
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
insertr/
|
||||
├── INITIAL.md # Project requirements and research
|
||||
├── DEVELOPMENT.md # This file
|
||||
├── package.json # Node.js project configuration
|
||||
├── .gitignore # Git ignore rules
|
||||
│
|
||||
├── demo-site/ # Frontend prototype
|
||||
│ ├── index.html # Demo homepage
|
||||
│ ├── about.html # Demo about page
|
||||
│ ├── README.md # Demo usage instructions
|
||||
│ │
|
||||
│ ├── assets/ # Demo site assets
|
||||
│ │ └── style.css # Demo site styling
|
||||
│ │
|
||||
│ ├── insertr/ # Core Insertr library
|
||||
│ │ ├── insertr.js # Main library file
|
||||
│ │ ├── insertr.css # Edit interface styles
|
||||
│ │ └── components/ # Future: reusable edit components
|
||||
│ │
|
||||
│ └── mock-api/ # Backend planning
|
||||
│ └── content.json # Sample data structure
|
||||
│
|
||||
└── backend/ # Future: Go backend
|
||||
├── main.go # Future: HTTP server
|
||||
├── api/ # Future: REST endpoints
|
||||
└── storage/ # Future: file-based storage
|
||||
```
|
||||
|
||||
## Development Scripts
|
||||
|
||||
- `npm run dev` - Start development server with live reload
|
||||
- `npm run dev:about` - Start server opening about page
|
||||
- `npm run build` - Future: Bundle library for distribution
|
||||
- `npm run test` - Future: Run tests
|
||||
- `npm run lint` - Future: Code linting
|
||||
|
||||
## Testing Different Scenarios
|
||||
|
||||
### Content Types
|
||||
- **Simple Text**: Logo, titles, short descriptions
|
||||
- **Rich Content**: Paragraphs with markdown, lists, links
|
||||
- **Mixed Content**: Cards with multiple editable sections
|
||||
|
||||
### User Flows
|
||||
1. **First Visit**: Customer sees clean site
|
||||
2. **Client Login**: Authentication state changes
|
||||
3. **Edit Mode**: Toggle editing interface
|
||||
4. **Content Editing**: Click edit → modify → save
|
||||
5. **Multi-page**: Test persistence across pages
|
||||
|
||||
### Browser Testing
|
||||
Test in different browsers to ensure compatibility:
|
||||
- Chrome/Edge (Chromium)
|
||||
- Firefox
|
||||
- Safari (if on macOS)
|
||||
|
||||
## Future Development Phases
|
||||
|
||||
### Phase 2: Backend Integration
|
||||
- Go HTTP server with REST API
|
||||
- Real authentication with Authentik OAuth
|
||||
- File-based content persistence
|
||||
- Git version control
|
||||
|
||||
### Phase 3: Production Features
|
||||
- Multi-tenant support
|
||||
- Admin dashboard
|
||||
- Content validation
|
||||
- Image upload
|
||||
- Deployment automation
|
||||
|
||||
## Contributing Guidelines
|
||||
|
||||
1. **Make changes** in small, focused commits
|
||||
2. **Test thoroughly** across different content types
|
||||
3. **Update documentation** when adding new features
|
||||
4. **Follow existing code style** and patterns
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
### JavaScript Console
|
||||
- Open browser dev tools (F12)
|
||||
- Check for errors in Console tab
|
||||
- Use `window.insertr` to inspect library state
|
||||
|
||||
### Local Storage
|
||||
- View saved content: `localStorage.getItem('insertr_content')`
|
||||
- Clear saved content: `localStorage.clear()`
|
||||
|
||||
### Network Simulation
|
||||
- The library simulates network delays and occasional failures
|
||||
- Check browser Network tab to see mock API calls (when implemented)
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Live Server Not Working
|
||||
- Ensure port 3000 is available
|
||||
- Try different port: `live-server demo-site --port=3001`
|
||||
|
||||
### Changes Not Reflecting
|
||||
- Hard refresh browser (Ctrl+F5 / Cmd+Shift+R)
|
||||
- Check browser cache settings
|
||||
- Verify file paths are correct
|
||||
|
||||
### Edit Buttons Not Showing
|
||||
- Check authentication state (click "Login as Client")
|
||||
- Enable edit mode (click "Edit Mode: Off" → "Edit Mode: On")
|
||||
- Verify elements have `class="insertr"` and `data-content-id`
|
||||
120
README.md
Normal file
120
README.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# Insertr
|
||||
|
||||
> **Edit-in-place CMS for client websites** - Simple integration with class-based content editing
|
||||
|
||||
Insertr allows developers to make any website content editable by simply adding a CSS class. Clients can then log in and edit content directly on their website without needing to learn a complex admin interface.
|
||||
|
||||
## ✨ The Vision
|
||||
|
||||
```html
|
||||
<!-- Developer adds this once -->
|
||||
<script src="https://insertr.example.com/insertr.js"></script>
|
||||
|
||||
<!-- Then marks content as editable -->
|
||||
<div class="insertr" data-content-id="hero">
|
||||
<h1>Your Editable Content</h1>
|
||||
</div>
|
||||
```
|
||||
|
||||
**That's it!** Your clients can now edit this content inline.
|
||||
|
||||
## 🎯 Three User Types
|
||||
|
||||
### 1. **The Customer** (End User)
|
||||
- Sees a clean, professional website
|
||||
- No editing interface visible
|
||||
- Fast loading with minimal overhead
|
||||
|
||||
### 2. **The Client** (Content Manager)
|
||||
- Logs in to see the same website with subtle edit buttons
|
||||
- Clicks edit buttons to modify content inline
|
||||
- Can edit both simple text and rich markdown content
|
||||
- Changes are saved immediately
|
||||
|
||||
### 3. **The Developer** (You)
|
||||
- Simple integration: just add `class="insertr"`
|
||||
- No complex setup or framework dependencies
|
||||
- Works with any existing website
|
||||
|
||||
## 🚀 Current Status
|
||||
|
||||
**✅ Frontend Prototype Complete**
|
||||
- Working edit-in-place functionality
|
||||
- Mock authentication system
|
||||
- Local persistence
|
||||
- Multi-page support
|
||||
- Responsive design
|
||||
|
||||
**🔄 In Development**
|
||||
- Go backend with REST API
|
||||
- Authentik OAuth integration
|
||||
- File-based content storage
|
||||
- Git version control
|
||||
|
||||
## 🛠️ Quick Start
|
||||
|
||||
1. **Clone and install**:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd insertr
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **Start development server**:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
3. **Open http://localhost:3000** and test the demo!
|
||||
|
||||
## 📖 Documentation
|
||||
|
||||
- **[Development Guide](DEVELOPMENT.md)** - Setup, workflow, and contribution guide
|
||||
- **[Demo Instructions](demo-site/README.md)** - How to test the prototype
|
||||
- **[Project Planning](INITIAL.md)** - Requirements, research, and roadmap
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
### Current (Phase 1)
|
||||
- **Frontend**: Vanilla JavaScript + Alpine.js
|
||||
- **Storage**: localStorage (for prototype)
|
||||
- **Authentication**: Mock system
|
||||
- **Deployment**: Static files
|
||||
|
||||
### Planned (Phase 2)
|
||||
- **Backend**: Go HTTP server
|
||||
- **Storage**: File-based with Git versioning
|
||||
- **Authentication**: Authentik OAuth 2.0
|
||||
- **Deployment**: Single binary + static files
|
||||
|
||||
### Future (Phase 3)
|
||||
- **Multi-tenant**: Host multiple client sites
|
||||
- **Admin Dashboard**: Advanced content management
|
||||
- **CDN Integration**: Global content delivery
|
||||
- **Plugin System**: Extensible functionality
|
||||
|
||||
## 🎬 Demo Features
|
||||
|
||||
**Try the prototype to see:**
|
||||
- ✏️ **Inline Editing** - Click edit buttons to modify content
|
||||
- 📝 **Rich Content** - Markdown editing for formatted text
|
||||
- 👤 **Authentication** - Login simulation with role switching
|
||||
- 💾 **Persistence** - Content saves automatically
|
||||
- 📱 **Responsive** - Works on desktop and mobile
|
||||
- 🔄 **Multi-page** - Consistent experience across pages
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
This project is in active development. See [DEVELOPMENT.md](DEVELOPMENT.md) for:
|
||||
- Development setup
|
||||
- Project structure
|
||||
- Testing guidelines
|
||||
- Future roadmap
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - see LICENSE file for details.
|
||||
|
||||
---
|
||||
|
||||
**Built with ❤️ for small business websites and their developers**
|
||||
2403
package-lock.json
generated
Normal file
2403
package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load Diff
45
package.json
Normal file
45
package.json
Normal file
@@ -0,0 +1,45 @@
|
||||
{
|
||||
"name": "insertr",
|
||||
"version": "0.1.0",
|
||||
"description": "Edit-in-place CMS for client websites - simple integration with class-based content editing",
|
||||
"main": "demo-site/insertr/insertr.js",
|
||||
"scripts": {
|
||||
"dev": "node scripts/dev.js serve",
|
||||
"dev:about": "live-server demo-site --port=3000 --open=/about.html",
|
||||
"dev:check": "node scripts/dev.js check",
|
||||
"dev:demo": "node scripts/dev.js demo",
|
||||
"dev:help": "node scripts/dev.js help",
|
||||
"build": "echo 'Build script placeholder - will bundle insertr.js for distribution'",
|
||||
"test": "echo 'Test script placeholder - will add tests for insertr.js'",
|
||||
"lint": "echo 'Linting placeholder - will add ESLint'",
|
||||
"serve": "npm run dev",
|
||||
"start": "npm run dev"
|
||||
},
|
||||
"keywords": [
|
||||
"cms",
|
||||
"edit-in-place",
|
||||
"inline-editing",
|
||||
"content-management",
|
||||
"client-websites",
|
||||
"go",
|
||||
"htmx",
|
||||
"alpine"
|
||||
],
|
||||
"author": "Your Name",
|
||||
"license": "MIT",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "git+https://github.com/yourusername/insertr.git"
|
||||
},
|
||||
"devDependencies": {
|
||||
"live-server": "^1.2.2"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=16.0.0",
|
||||
"npm": ">=8.0.0"
|
||||
},
|
||||
"browserslist": [
|
||||
"defaults",
|
||||
"not IE 11"
|
||||
]
|
||||
}
|
||||
115
scripts/dev.js
Executable file
115
scripts/dev.js
Executable file
@@ -0,0 +1,115 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Development helper script for Insertr
|
||||
* Provides common development tasks and utilities
|
||||
*/
|
||||
|
||||
const { execSync, spawn } = require('child_process');
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
|
||||
const commands = {
|
||||
serve: {
|
||||
description: 'Start development server with live reload',
|
||||
action: () => {
|
||||
console.log('🚀 Starting Insertr development server...');
|
||||
console.log('📂 Serving demo-site/ at http://localhost:3000');
|
||||
console.log('🔄 Live reload enabled');
|
||||
console.log('\n💡 Test the three user types:');
|
||||
console.log(' 👥 Customer: Visit the site normally');
|
||||
console.log(' ✏️ Client: Click "Login as Client" → "Edit Mode: On"');
|
||||
console.log(' 🔧 Developer: View source to see integration\n');
|
||||
|
||||
spawn('npx', ['live-server', 'demo-site', '--port=3000', '--open=/index.html'], {
|
||||
stdio: 'inherit'
|
||||
});
|
||||
}
|
||||
},
|
||||
|
||||
check: {
|
||||
description: 'Check project status and validate setup',
|
||||
action: () => {
|
||||
console.log('🔍 Checking Insertr project status...\n');
|
||||
|
||||
// Check files exist
|
||||
const requiredFiles = [
|
||||
'demo-site/index.html',
|
||||
'demo-site/about.html',
|
||||
'demo-site/insertr/insertr.js',
|
||||
'demo-site/insertr/insertr.css',
|
||||
'package.json'
|
||||
];
|
||||
|
||||
let allGood = true;
|
||||
|
||||
requiredFiles.forEach(file => {
|
||||
if (fs.existsSync(file)) {
|
||||
console.log('✅', file);
|
||||
} else {
|
||||
console.log('❌', file, '(missing)');
|
||||
allGood = false;
|
||||
}
|
||||
});
|
||||
|
||||
if (allGood) {
|
||||
console.log('\n🎉 All core files present!');
|
||||
console.log('\n📊 Project stats:');
|
||||
|
||||
// Count editable elements
|
||||
const indexContent = fs.readFileSync('demo-site/index.html', 'utf8');
|
||||
const aboutContent = fs.readFileSync('demo-site/about.html', 'utf8');
|
||||
const insertrMatches = (indexContent + aboutContent).match(/class="insertr"/g) || [];
|
||||
console.log(` 📝 Editable elements: ${insertrMatches.length}`);
|
||||
|
||||
// Check library size
|
||||
const libSize = fs.statSync('demo-site/insertr/insertr.js').size;
|
||||
console.log(` 📦 Library size: ${(libSize / 1024).toFixed(1)}KB`);
|
||||
|
||||
console.log('\n🚀 Ready to develop! Run: npm run dev');
|
||||
} else {
|
||||
console.log('\n❌ Some files are missing. Please check your setup.');
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
demo: {
|
||||
description: 'Show demo instructions',
|
||||
action: () => {
|
||||
console.log('🎬 Insertr Demo Instructions\n');
|
||||
console.log('1. 🌐 Start server: npm run dev');
|
||||
console.log('2. 👀 Customer view: Browse the site normally');
|
||||
console.log('3. 🔑 Client login: Click "Login as Client"');
|
||||
console.log('4. ✏️ Edit mode: Click "Edit Mode: Off" to enable editing');
|
||||
console.log('5. 📝 Edit content: Click any ✏️ button to edit');
|
||||
console.log('6. 🔄 Try different content types (simple text vs rich markdown)');
|
||||
console.log('7. 📄 Multi-page: Navigate to About page to see persistence\n');
|
||||
console.log('🎯 Key features to test:');
|
||||
console.log(' • Inline text editing');
|
||||
console.log(' • Markdown editing for rich content');
|
||||
console.log(' • Auto-save with visual feedback');
|
||||
console.log(' • Content persistence across pages');
|
||||
console.log(' • Responsive design on mobile\n');
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
// Parse command line arguments
|
||||
const command = process.argv[2] || 'help';
|
||||
|
||||
if (commands[command]) {
|
||||
commands[command].action();
|
||||
} else if (command === 'help' || command === '--help' || command === '-h') {
|
||||
console.log('🛠️ Insertr Development Helper\n');
|
||||
console.log('Available commands:\n');
|
||||
Object.entries(commands).forEach(([name, cmd]) => {
|
||||
console.log(` ${name.padEnd(12)} ${cmd.description}`);
|
||||
});
|
||||
console.log('\nUsage: node scripts/dev.js <command>');
|
||||
console.log(' or: npm run dev:help\n');
|
||||
} else {
|
||||
console.log(`❌ Unknown command: ${command}`);
|
||||
console.log('Run: node scripts/dev.js help');
|
||||
process.exit(1);
|
||||
}
|
||||
Reference in New Issue
Block a user