Initial commit
This commit is contained in:
Zhongwei Li
241
references/migration-from-decap.md
Normal file
241
references/migration-from-decap.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# Migrating from Decap CMS to Sveltia CMS
|
||||
|
||||
**TL;DR**: Change 1 line in `admin/index.html`. Your config.yml works as-is.
|
||||
|
||||
---
|
||||
|
||||
## Why Migrate?
|
||||
|
||||
**Sveltia CMS** is the modern successor to Decap CMS (formerly Netlify CMS) with:
|
||||
|
||||
- ✅ **5x smaller bundle** (300 KB vs 1.5 MB)
|
||||
- ✅ **Faster performance** (GraphQL, instant loading)
|
||||
- ✅ **260+ issues solved** from Decap CMS
|
||||
- ✅ **Better mobile support**
|
||||
- ✅ **Dark mode** built-in
|
||||
- ✅ **Active maintenance** (frequent releases)
|
||||
- ✅ **100% config compatible**
|
||||
|
||||
---
|
||||
|
||||
## Migration Steps
|
||||
|
||||
### Step 1: Update Script Tag
|
||||
|
||||
**Location**: `static/admin/index.html` (Hugo) or `admin/index.html` (Jekyll/11ty)
|
||||
|
||||
**OLD (Decap CMS)**:
|
||||
```html
|
||||
<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
|
||||
```
|
||||
|
||||
**NEW (Sveltia CMS)**:
|
||||
```html
|
||||
<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
|
||||
```
|
||||
|
||||
**Important**: Add `type="module"` attribute!
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Keep Existing Config
|
||||
|
||||
```yaml
|
||||
# admin/config.yml - NO CHANGES NEEDED!
|
||||
backend:
|
||||
name: github
|
||||
repo: owner/repo
|
||||
branch: main
|
||||
# base_url: ... (keep if using OAuth proxy)
|
||||
|
||||
media_folder: static/images
|
||||
public_folder: /images
|
||||
|
||||
collections:
|
||||
# ... all your existing collections work as-is
|
||||
```
|
||||
|
||||
**Your entire config.yml is 100% compatible!**
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Test Locally
|
||||
|
||||
```bash
|
||||
# Start your site's dev server
|
||||
hugo server # or jekyll serve, or npm run dev
|
||||
|
||||
# Visit admin
|
||||
open http://localhost:1313/admin/ # (or your port)
|
||||
```
|
||||
|
||||
**Test these workflows**:
|
||||
- ✅ Login (should work with existing OAuth)
|
||||
- ✅ View content list
|
||||
- ✅ Edit existing entry
|
||||
- ✅ Create new entry
|
||||
- ✅ Upload image
|
||||
- ✅ Save and publish
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Deploy
|
||||
|
||||
```bash
|
||||
git add static/admin/index.html # or your admin path
|
||||
git commit -m "Migrate to Sveltia CMS from Decap CMS"
|
||||
git push
|
||||
```
|
||||
|
||||
**That's it!** Your site rebuilds with Sveltia CMS.
|
||||
|
||||
---
|
||||
|
||||
## What Changes?
|
||||
|
||||
### UI Changes (Better UX)
|
||||
|
||||
- **Performance**: Instant content loading (GraphQL)
|
||||
- **Search**: Full-text search across all content
|
||||
- **Mobile**: Better mobile and tablet experience
|
||||
- **Dark Mode**: Automatic dark mode support
|
||||
- **Image Optimization**: Built-in WebP conversion
|
||||
|
||||
### What Stays the Same
|
||||
|
||||
- **Content**: All your Markdown/JSON/YAML files unchanged
|
||||
- **Collections**: Same collection definitions
|
||||
- **Fields**: Same field widgets and validation
|
||||
- **Workflows**: Same editorial workflow
|
||||
- **Media**: Same media folder and uploads
|
||||
|
||||
---
|
||||
|
||||
## What's Not Supported?
|
||||
|
||||
Sveltia CMS deliberately omits these Decap features for performance:
|
||||
|
||||
- ❌ **Git Gateway backend** (use OAuth proxy instead)
|
||||
- ❌ **Azure backend** (may be added later)
|
||||
- ❌ **Bitbucket backend** (may be added later)
|
||||
|
||||
**If you use Git Gateway**, switch to **Cloudflare Workers OAuth** (faster, more reliable):
|
||||
- See: `templates/cloudflare-workers/setup-guide.md`
|
||||
- Takes 10 minutes to set up
|
||||
- Free tier: 100k requests/day
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
Before fully migrating, verify these work:
|
||||
|
||||
- [ ] Login with OAuth
|
||||
- [ ] View all collections
|
||||
- [ ] Edit existing content
|
||||
- [ ] Create new content
|
||||
- [ ] Upload images
|
||||
- [ ] Publish/unpublish works
|
||||
- [ ] Search functionality
|
||||
- [ ] Mobile editing (if applicable)
|
||||
- [ ] i18n switching (if applicable)
|
||||
|
||||
---
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If you need to rollback:
|
||||
|
||||
1. **Revert script tag** to Decap CMS:
|
||||
```html
|
||||
<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
|
||||
```
|
||||
|
||||
2. **Commit and push**:
|
||||
```bash
|
||||
git add static/admin/index.html
|
||||
git commit -m "Rollback to Decap CMS"
|
||||
git push
|
||||
```
|
||||
|
||||
**Your content and config are unchanged** - you can switch back and forth freely!
|
||||
|
||||
---
|
||||
|
||||
## Common Migration Issues
|
||||
|
||||
### Issue: "SVELTIA is not defined"
|
||||
|
||||
**Cause**: Missing `type="module"` attribute
|
||||
|
||||
**Fix**:
|
||||
```html
|
||||
<!-- Correct -->
|
||||
<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>
|
||||
|
||||
<!-- Wrong - missing type="module" -->
|
||||
<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: OAuth Not Working
|
||||
|
||||
**Cause**: Using Git Gateway (not supported)
|
||||
|
||||
**Fix**: Switch to Cloudflare Workers OAuth:
|
||||
1. Deploy OAuth Worker (5 min)
|
||||
2. Update config.yml with `base_url`
|
||||
3. Test authentication
|
||||
|
||||
See: `templates/cloudflare-workers/setup-guide.md`
|
||||
|
||||
---
|
||||
|
||||
### Issue: TOML Files Not Loading
|
||||
|
||||
**Cause**: Sveltia's TOML support is buggy in beta
|
||||
|
||||
**Fix**: Use YAML instead:
|
||||
```yaml
|
||||
collections:
|
||||
- name: posts
|
||||
folder: content/posts
|
||||
format: yaml # Change from: toml
|
||||
```
|
||||
|
||||
Or wait for TOML fixes in future releases.
|
||||
|
||||
---
|
||||
|
||||
## Performance Comparison
|
||||
|
||||
| Metric | Decap CMS | Sveltia CMS | Improvement |
|
||||
|--------|-----------|-------------|-------------|
|
||||
| **Bundle Size** | 1.5 MB | 300 KB | **5x smaller** |
|
||||
| **Initial Load** | 2-3 sec | 0.5-1 sec | **3x faster** |
|
||||
| **Content Listing** | Sequential API calls | Single GraphQL query | **10x faster** |
|
||||
| **Search** | Client-side only | Full-text | **Much better** |
|
||||
| **Mobile UX** | Poor | Good | **Significantly improved** |
|
||||
|
||||
---
|
||||
|
||||
## Support & Help
|
||||
|
||||
**Issues after migration?**
|
||||
- GitHub: https://github.com/sveltia/sveltia-cms/issues
|
||||
- Discussions: https://github.com/sveltia/sveltia-cms/discussions
|
||||
|
||||
**Questions about Decap compatibility?**
|
||||
- Sveltia maintainer is very responsive
|
||||
- Most Decap configs work without changes
|
||||
|
||||
---
|
||||
|
||||
**Migration Time**: 5-10 minutes
|
||||
**Risk Level**: Very Low (config unchanged, easy rollback)
|
||||
**Recommended**: Yes (significant improvements)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-10-24
|
||||
Reference in New Issue
Block a user