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