Guides & Tutorials
Comprehensive guides to help you master pushduck - from basic uploads to advanced patterns and production deployment
Learning Path & Tutorials
Learn how to build robust file upload features with pushduck through comprehensive guides covering everything from basic uploads to advanced production patterns.
Progressive Learning: These guides are organized from basic concepts to advanced patterns. Start with client approaches and work your way up to production deployment.
Getting Started
Upload Patterns
Security & Authentication
Authentication & Authorization
Secure your uploads with proper authentication patterns
- User authentication strategies
- Role-based access control
- JWT integration
- Session management
Essential for: Secure applications
CORS & ACL Configuration
Configure cross-origin requests and access control
- CORS setup for different providers
- Access Control Lists (ACL)
- Public vs private uploads
- Security best practices
Essential for: Production deployments
Migration & Upgrades
Production Deployment
Common Patterns
Basic Upload Flow
Configure Server Router
Set up your upload routes with validation:
const uploadRouter = createS3Router({
routes: {
imageUpload: s3.image().maxFileSize("5MB"),
documentUpload: s3.file().maxFileSize("10MB"),
},
});Implement Client Upload
Use hooks or client for reactive uploads:
const { upload, uploading, progress } = useUpload({
endpoint: '/api/upload',
route: 'imageUpload',
});Handle Upload Results
Process successful uploads and errors:
const result = await upload(file);
console.log('File uploaded:', result.url);Authentication Pattern
// Server: Add authentication middleware
const uploadRouter = createS3Router({
middleware: [
async (req) => {
const user = await authenticate(req);
if (!user) throw new Error('Unauthorized');
return { user };
}
],
routes: {
userAvatar: s3.image()
.maxFileSize("2MB")
.path(({ metadata }) => `avatars/${metadata.user.id}`),
},
});
// Client: Include auth headers
const { upload } = useUpload({
endpoint: '/api/upload',
route: 'userAvatar',
headers: {
Authorization: `Bearer ${token}`,
},
});Architecture Patterns
Multi-Provider Setup
// Support multiple storage providers
const uploadRouter = createS3Router({
storage: process.env.NODE_ENV === 'production'
? { provider: 'aws-s3', ... }
: { provider: 'minio', ... },
routes: {
// Your routes remain the same
},
});Route-Based Organization
const uploadRouter = createS3Router({
routes: {
// Public uploads
publicImages: s3.image().maxFileSize("5MB").public(),
// User-specific uploads
userDocuments: s3.file()
.maxFileSize("10MB")
.path(({ metadata }) => `users/${metadata.userId}/documents`),
// Admin uploads
adminAssets: s3.file()
.maxFileSize("50MB")
.middleware([requireAdmin]),
},
});Performance Tips
Optimization Strategies:
- Use appropriate file size limits for your use case
- Implement client-side validation before upload
- Consider using presigned URLs for large files
- Enable CDN for frequently accessed files
- Implement progressive upload for large files
Troubleshooting Quick Links
| Issue | Solution |
|---|---|
| CORS errors | Check CORS Configuration |
| Auth failures | Review Authentication Guide |
| Slow uploads | See Production Checklist |
| Type errors | Check Enhanced Client Migration |
What's Next?
- New to pushduck? → Start with Client Approaches
- Building image features? → Check Image Uploads
- Adding security? → Review Authentication
- Going to production? → Use Production Checklist
- Need help? → Visit our troubleshooting guide
Community Guides: Have a useful pattern or solution? Consider contributing to our documentation to help other developers!