Add preview handling
This commit is contained in:
nicwands
193
STRAPI_PREVIEW_SETUP.md
Normal file
193
STRAPI_PREVIEW_SETUP.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# Strapi Preview Implementation for Vike App
|
||||
|
||||
This document explains how to set up and use the Strapi Preview feature with this Vike application.
|
||||
|
||||
## Features Implemented
|
||||
|
||||
✅ **Basic Preview** - Preview draft and published content from Strapi admin
|
||||
✅ **Dynamic Routes** - Support for articles, pages, and other content types
|
||||
✅ **Preview Banner** - Visual indicator when in preview mode
|
||||
✅ **Live Preview Ready** - Communication setup for real-time content updates
|
||||
✅ **Security** - CSP headers for safe iframe embedding
|
||||
✅ **Cache Control** - Preview content bypasses caching
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
### 1. Frontend Configuration (Already Done)
|
||||
|
||||
The Vike app is now configured with:
|
||||
|
||||
- **Environment Variables** (`.env`):
|
||||
```bash
|
||||
VITE_CLIENT_URL=https://takerofnotes.com
|
||||
VITE_PREVIEW_SECRET=preview-secret-key-change-this-in-production
|
||||
```
|
||||
|
||||
- **Preview Route**: `/pages/preview/+data.js` and `/pages/preview/+Page.vue`
|
||||
- **Enhanced Strapi Client**: Preview-aware data fetching
|
||||
- **UI Components**: Preview banner and Live Preview communication
|
||||
- **CSP Headers**: Allow embedding from Strapi admin
|
||||
|
||||
### 2. Strapi Configuration (To Do)
|
||||
|
||||
1. **Copy the admin configuration** from `strapi-config-example.js` to your Strapi project at `config/admin.js`
|
||||
|
||||
2. **Add environment variables** to your Strapi `.env`:
|
||||
```bash
|
||||
CLIENT_URL=https://takerofnotes.com
|
||||
PREVIEW_SECRET=preview-secret-key-change-this-in-production
|
||||
```
|
||||
|
||||
3. **Update the preview secret** in both frontend and Strapi to match
|
||||
|
||||
### 3. Content Type Setup
|
||||
|
||||
The implementation supports these content type patterns:
|
||||
|
||||
- **Global** (`api::global.global`) → `/` (homepage)
|
||||
- **Pages** (`api::page.page`) → `/{slug}`
|
||||
- **Articles** (`api::article.article`) → `/articles/{slug}`
|
||||
|
||||
Add more content types by:
|
||||
1. Updating `getPreviewPathname()` in the Strapi config
|
||||
2. Creating corresponding route files in `/pages/`
|
||||
|
||||
## How It Works
|
||||
|
||||
### Preview Flow
|
||||
|
||||
1. **Strapi Admin** → User clicks "Open Preview" on content
|
||||
2. **Preview Handler** → Generates preview URL with secret and parameters
|
||||
3. **Preview API** → Validates secret and redirects to content page with preview flags
|
||||
4. **Content Page** → Detects preview mode and fetches draft content
|
||||
5. **Preview Banner** → Shows preview status with exit option
|
||||
|
||||
### URL Structure
|
||||
|
||||
Preview URLs follow this pattern:
|
||||
```
|
||||
/preview?secret=xxx&path=/articles/my-article&status=draft&documentId=123&uid=api::article.article
|
||||
```
|
||||
|
||||
Which redirects to:
|
||||
```
|
||||
/articles/my-article?preview=true&status=draft&documentId=123&uid=api::article.article
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
├── pages/
|
||||
│ ├── preview/ # Preview route handler
|
||||
│ │ ├── +Page.vue
|
||||
│ │ └── +data.js
|
||||
│ ├── @slug/ # Dynamic pages route
|
||||
│ │ ├── +Page.vue
|
||||
│ │ └── +data.js
|
||||
│ ├── articles/@slug/ # Dynamic articles route
|
||||
│ │ ├── +Page.vue
|
||||
│ │ └── +data.js
|
||||
│ ├── index/+data.js # Homepage with preview support
|
||||
│ └── +Layout.vue # Updated with preview components
|
||||
├── components/
|
||||
│ ├── PreviewBanner.vue # Preview mode indicator
|
||||
│ └── LivePreview.vue # Live Preview communication
|
||||
├── libs/
|
||||
│ └── strapi.js # Enhanced with preview support
|
||||
└── strapi-config-example.js # Strapi admin configuration
|
||||
```
|
||||
|
||||
## Adding New Content Types
|
||||
|
||||
To add preview support for a new content type:
|
||||
|
||||
1. **Update Strapi Config** (`config/admin.js`):
|
||||
```js
|
||||
case "api::my-content.my-content":
|
||||
return `/my-content/${slug}`;
|
||||
```
|
||||
|
||||
2. **Create Vike Route**:
|
||||
```
|
||||
pages/my-content/@slug/
|
||||
├── +Page.vue
|
||||
└── +data.js
|
||||
```
|
||||
|
||||
3. **Implement Data Fetching**:
|
||||
```js
|
||||
import { getBySlug, getByDocumentId } from '@/libs/strapi'
|
||||
|
||||
export const data = async (pageContext) => {
|
||||
// Extract preview parameters
|
||||
const isPreview = searchParams.preview === 'true'
|
||||
const status = searchParams.status || 'published'
|
||||
|
||||
// Fetch with preview support
|
||||
const response = await getBySlug('my-content', slug, {
|
||||
isPreview,
|
||||
status
|
||||
})
|
||||
|
||||
return { content: response.data, isPreview, status }
|
||||
}
|
||||
```
|
||||
|
||||
## Security Notes
|
||||
|
||||
- **Preview Secret**: Change the default secret in production
|
||||
- **CSP Headers**: Only allow embedding from your Strapi domain
|
||||
- **Environment Variables**: Use `VITE_` prefix for client-side access
|
||||
- **Validation**: Preview API validates secret before redirecting
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Preview Mode
|
||||
|
||||
1. Add `?preview=true&status=draft` to any URL
|
||||
2. Should see orange preview banner
|
||||
3. Content should be fetched with draft status
|
||||
|
||||
### Test Preview Route
|
||||
|
||||
Visit: `/preview?secret=your-secret&path=/&status=draft`
|
||||
Should redirect to: `/?preview=true&status=draft`
|
||||
|
||||
## Live Preview (Strapi Growth/Enterprise)
|
||||
|
||||
The implementation includes Live Preview communication:
|
||||
|
||||
- **Real-time Updates**: Content changes in Strapi trigger page refresh
|
||||
- **Interactive Editing**: Double-click content to edit (with proper source maps)
|
||||
- **Source Maps**: Enable with `strapi-encode-source-maps` header
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Preview Not Working
|
||||
|
||||
- Check environment variables match between frontend and Strapi
|
||||
- Verify CSP headers allow iframe embedding
|
||||
- Ensure Strapi admin config is properly deployed
|
||||
|
||||
### Content Not Loading
|
||||
|
||||
- Check Strapi API authentication
|
||||
- Verify content type exists and has proper permissions
|
||||
- Check browser network tab for failed requests
|
||||
|
||||
### Preview Banner Not Showing
|
||||
|
||||
- Verify URL contains `preview=true` parameter
|
||||
- Check component import in Layout
|
||||
- Ensure data is being passed correctly
|
||||
|
||||
## Development vs Production
|
||||
|
||||
### Development
|
||||
- Use `http://localhost:3000` as CLIENT_URL
|
||||
- Preview works locally during development
|
||||
|
||||
### Production
|
||||
- Update CLIENT_URL to your production domain
|
||||
- Ensure HTTPS for iframe embedding
|
||||
- Update preview secret for security
|
||||
Reference in New Issue
Block a user