Creating Theme Packs
Theme packs are bundles of related components that power your pages. Build them locally in your editor, register them in the desktop app, and sync them to the cloud when you are ready to publish.
What is a Theme Pack?
A theme pack is a collection of related components bundled together. Each component is a self-contained island with its own schema, fully hydrated and ready to render. Grouped together, they form a cohesive set of building blocks for creating pages. The desktop app manages your local theme packs and handles building and syncing them to the cloud.
Creating a Theme Pack
1. Initialize your project
Create a new theme pack project using the CLI. Choose your framework when prompted:
oaysus theme init marketing-starterThis creates a project folder with a starter component and the required package.json structure.
2. Configure your theme pack
Theme pack metadata lives in package.json. Add a display name, category, and tags for discoverability:
1{
2 "name": "marketing-starter",
3 "version": "1.0.0",
4 "description": "Landing page components for marketing sites",
5 "oaysus": {
6 "displayName": "Marketing Starter",
7 "category": "marketing",
8 "tags": ["landing-page", "saas", "startup"]
9 },
10 "framework": "react"
11}3. Add a banner image
Add a marketing/banner.png file to display in the theme pack gallery. This image appears when users browse and preview your theme pack.
marketing/banner.png4. Add components
Use the CLI to scaffold new components, or create them manually in the components/ directory:
oaysus theme create FeatureGridA typical theme pack structure looks like this:
marketing-starter/ ├── components/ │ ├── HeroBanner/ │ │ ├── index.tsx │ │ └── schema.json │ ├── FeatureGrid/ │ │ ├── index.tsx │ │ └── schema.json │ ├── Testimonials/ │ │ ├── index.tsx │ │ └── schema.json │ └── PricingTable/ │ ├── index.tsx │ └── schema.json ├── marketing/ │ └── banner.png ├── shared/ ├── package.json └── README.md
5. Validate your pack
Check for errors before registering or publishing:
oaysus theme validatePublishing Your Theme Pack
Using the desktop app (recommended)
The desktop app manages the full build and sync lifecycle. Register your theme pack once, then rebuild and sync whenever you make changes.
- 1Open the desktop app and go to Theme Packs
- 2Click Add Existing and select your theme pack folder, or click Create New to scaffold a new pack directly from the app
- 3The desktop app builds your components automatically on registration
- 4Go to the Sync tab and click Sync Up to push your theme pack to the cloud
After syncing, click Rebuild on any theme pack card to rebuild locally before your next sync.
After syncing
Your theme pack is now available. Go to Content › Theme Packs in the dashboard to install it on any site.
Versioning
Theme pack versions are controlled by the version field in your package.json. Use semantic versioning:
1.0.0 → 1.0.1Bug fixes, no breaking changes1.0.0 → 1.1.0New components added1.0.0 → 2.0.0Breaking changes to existing componentsTo publish an update:
- 1Bump the
versionfield inpackage.json - 2Click Rebuild on the theme pack card in the desktop app to rebuild with the new version
- 3Go to the Sync tab and run Sync Up to push the update to the cloud
Installing Theme Packs
From the dashboard
After syncing your pack to the cloud, install it on a site from the Oaysus dashboard:
- 1Go to Content › Theme Packs in the dashboard
- 2Find your theme pack and click Install
- 3All components from the pack are now available in the page builder
- 4Drag components onto your pages and customize their content
From the desktop app
Registered theme packs are available immediately in the desktop app’s page builder. No installation step is required. Open any page and the components from all registered packs appear in the component picker.
Categories
Set a category in your package.json to help users discover your theme pack: