@osimart/create-storefront 1.0.26 → 1.0.27
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +182 -50
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,42 +1,99 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Osimart Storefront
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
`@Osimart/create-storefront` is the shared storefront platform for Osimart themes. It provides the Nuxt foundation, store-facing pages, commerce behavior, reusable UI, theme integration, and the `Osimart-theme` developer CLI. A theme extends this package and supplies its own presentation: page layouts, section markup, component styling, assets, and theme configuration.
|
|
4
|
+
|
|
5
|
+
This package is intended to be consumed by an Osimart theme project. It is not a standalone store template. The theme project is where you build the customer-facing look; this package supplies the shared platform that powers it.
|
|
6
|
+
|
|
7
|
+
## How the pieces fit together
|
|
8
|
+
|
|
9
|
+
| Part | Owns |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| `@Osimart/create-storefront` (this package) | Nuxt configuration, routes, shared commerce and account behavior, platform components, theme utilities, and the theme CLI |
|
|
12
|
+
| Osimart theme project | Layouts, section and component markup, CSS, images and fonts, section schemas, and theme JSON settings |
|
|
13
|
+
| Osimart store service | Store data and API operations used by the storefront and theme tools |
|
|
14
|
+
|
|
15
|
+
The platform exposes logic for theme files through `#logic`. A theme can use that logic while keeping control of its Vue template and styles. This lets shared behavior improve across themes without forcing every theme to use the same design.
|
|
16
|
+
|
|
17
|
+
## Requirements
|
|
18
|
+
|
|
19
|
+
- Node.js and npm versions supported by your Nuxt project.
|
|
20
|
+
- An Osimart theme repository or a new theme project based on the Osimart theme structure.
|
|
21
|
+
- Access to the `@osimart/create-storefront` package registry if the package is private in your environment.
|
|
22
|
+
- An Osimart store API URL and a theme access token for commands that read or write a store's theme.
|
|
23
|
+
|
|
24
|
+
## Add the platform to a theme project
|
|
25
|
+
|
|
26
|
+
Install the package in the theme project:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm install @osimart/create-storefront
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
If registry authentication is required, configure npm using the credentials provided for your Osimart development environment. Do not commit access tokens to the repository.
|
|
33
|
+
|
|
34
|
+
Extend the platform from the theme's `nuxt.config.ts`:
|
|
5
35
|
|
|
6
36
|
```ts
|
|
7
|
-
|
|
8
|
-
|
|
37
|
+
export default defineNuxtConfig({
|
|
38
|
+
extends: ["@osimart/create-storefront"],
|
|
39
|
+
});
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The layer configures the `#osi` alias for platform app code, the `#logic` alias for shared theme logic, global platform components, and the section registry module. The theme can add its own components and section files in the usual Nuxt locations.
|
|
43
|
+
|
|
44
|
+
Install the theme project's remaining dependencies and start it using its scripts. For example, the Osimart base theme uses:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npm install
|
|
48
|
+
npm run dev
|
|
9
49
|
```
|
|
10
50
|
|
|
11
|
-
|
|
12
|
-
|---|---|---|
|
|
13
|
-
| Platform (hidden, updates everyone) | Shopify's servers | this package |
|
|
14
|
-
| Theme (Dawn) | sections, snippets, layout, assets | `osimart-theme-base` repo |
|
|
15
|
-
| Theme JSON | `templates/*.json`, `sections/*-group.json`, `config/settings_data.json` | `theme/` in the theme repo, `osimart-theme pull/push` |
|
|
16
|
-
| A store's custom theme | copy of Dawn | a repo created from `osimart-theme-base` |
|
|
51
|
+
The base theme's `dev` script runs `Osimart-theme dev`, which starts Nuxt in a theme development session. Use `npm run dev:live` when you specifically need to run plain `nuxt dev` without the theme preview session.
|
|
17
52
|
|
|
18
|
-
##
|
|
53
|
+
## Configure the store connection
|
|
19
54
|
|
|
55
|
+
Set environment variables in the theme project's local `.env` file. The exact API host depends on your Osimart environment:
|
|
56
|
+
|
|
57
|
+
```dotenv
|
|
58
|
+
NUXT_PUBLIC_STORE_API_BASE=https://your-store-api.example/
|
|
59
|
+
Osimart_THEME_TOKEN=your-theme-access-token
|
|
20
60
|
```
|
|
61
|
+
|
|
62
|
+
`NUXT_PUBLIC_STORE_API_BASE` is the API base used by the storefront. The theme CLI also uses it to reach the theme development API. `Osimart_THEME_TOKEN` authorizes theme CLI operations. Keep the token private and out of source control.
|
|
63
|
+
|
|
64
|
+
In production, the storefront API is same-origin by default; the Nuxt runtime config's `storeApiBase` defaults to an empty string. Configure the deployment and API routing for your Osimart environment accordingly. The public runtime setting can be overridden with `NUXT_PUBLIC_STORE_API_BASE` when needed.
|
|
65
|
+
|
|
66
|
+
## Project structure
|
|
67
|
+
|
|
68
|
+
The main platform areas are:
|
|
69
|
+
|
|
70
|
+
```text
|
|
21
71
|
app/
|
|
22
|
-
├── logic/
|
|
23
|
-
│ ├── sections/
|
|
24
|
-
│ ├── components/
|
|
25
|
-
│ └── layouts/
|
|
26
|
-
├──
|
|
27
|
-
├──
|
|
28
|
-
│
|
|
29
|
-
│
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
├──
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
72
|
+
├── logic/
|
|
73
|
+
│ ├── sections/ Shared behavior used by theme section components
|
|
74
|
+
│ ├── components/ Shared behavior used by theme components
|
|
75
|
+
│ └── layouts/ Shared layout behavior
|
|
76
|
+
├── pages/ Platform routes such as checkout, login, and account pages
|
|
77
|
+
├── components/
|
|
78
|
+
│ ├── checkout/ Checkout UI
|
|
79
|
+
│ ├── common/ Shared controls and UI primitives
|
|
80
|
+
│ └── builder/ Theme builder and preview UI
|
|
81
|
+
├── composables/ Reusable Vue/Nuxt behavior
|
|
82
|
+
├── services/ API and domain service code
|
|
83
|
+
├── stores/ Pinia stores
|
|
84
|
+
└── theme/ Theme registries and control helpers
|
|
85
|
+
bin/Osimart-theme.mjs Theme development and synchronization CLI
|
|
86
|
+
nuxt/ Nuxt modules for section registration and dev preview
|
|
87
|
+
THEME_DEV_API.md Theme CLI API contract
|
|
37
88
|
```
|
|
38
89
|
|
|
39
|
-
|
|
90
|
+
The consuming theme typically contains its own `app/sections`, `app/components`, `app/layouts`, styles, public assets, and a `theme/` directory with its settings, section groups, and page templates.
|
|
91
|
+
|
|
92
|
+
## Customize a theme
|
|
93
|
+
|
|
94
|
+
### Change a section's markup or styling
|
|
95
|
+
|
|
96
|
+
Theme section files own their template and CSS. Import the matching platform logic when the section needs shared data or behavior:
|
|
40
97
|
|
|
41
98
|
```vue
|
|
42
99
|
<script setup>
|
|
@@ -46,36 +103,111 @@ const props = defineProps({ section: Object, index: Number });
|
|
|
46
103
|
const { asBanner } = useLogic({ props });
|
|
47
104
|
</script>
|
|
48
105
|
|
|
49
|
-
<template
|
|
106
|
+
<template>
|
|
107
|
+
<MediaWithTextSection :section="asBanner" :index="index" />
|
|
108
|
+
</template>
|
|
109
|
+
|
|
110
|
+
<style scoped>
|
|
111
|
+
/* Theme-specific presentation */
|
|
112
|
+
</style>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Keep the props and emitted events expected by the shared component logic. The logic's returned values are part of the theme integration API: adding a returned value is generally compatible, while renaming or removing one can break consuming themes.
|
|
116
|
+
|
|
117
|
+
### Override a platform component
|
|
118
|
+
|
|
119
|
+
Create a theme component with the same component name and Nuxt will resolve the theme implementation for that theme. Use the shared component logic where appropriate, then own the template and style in the theme. This is useful when a theme needs a different design while preserving established cart, product, or navigation behavior.
|
|
120
|
+
|
|
121
|
+
### Add a section type
|
|
122
|
+
|
|
123
|
+
Create a Vue section and its schema in the theme project. For example:
|
|
124
|
+
|
|
125
|
+
`app/sections/LookbookSection.vue`
|
|
126
|
+
|
|
127
|
+
```vue
|
|
128
|
+
<script setup>
|
|
129
|
+
const props = defineProps({ section: Object, index: Number });
|
|
130
|
+
</script>
|
|
131
|
+
|
|
132
|
+
<template>
|
|
133
|
+
<section class="lookbook">
|
|
134
|
+
<h2>{{ section.settings?.HEADING }}</h2>
|
|
135
|
+
</section>
|
|
136
|
+
</template>
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
`app/sections/LookbookSection.schema.json`
|
|
140
|
+
|
|
141
|
+
```json
|
|
142
|
+
{
|
|
143
|
+
"name": "Lookbook",
|
|
144
|
+
"templates": ["INDEX", "PAGE"],
|
|
145
|
+
"settings": [
|
|
146
|
+
{ "id": "HEADING", "type": "text", "label": "Heading" }
|
|
147
|
+
],
|
|
148
|
+
"blocks": []
|
|
149
|
+
}
|
|
50
150
|
```
|
|
51
151
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
and
|
|
152
|
+
The section registry discovers theme section files. The schema describes the settings and blocks available to the Osimart theme editor. Push the theme to synchronize the schema with the store, then add the section to the relevant theme template or group.
|
|
153
|
+
|
|
154
|
+
### Customize theme settings and page composition
|
|
155
|
+
|
|
156
|
+
Theme JSON is stored in the theme project's `theme/` directory:
|
|
157
|
+
|
|
158
|
+
```text
|
|
159
|
+
theme/
|
|
160
|
+
├── config/settings_data.json
|
|
161
|
+
├── sections/header-group.json
|
|
162
|
+
├── sections/footer-group.json
|
|
163
|
+
└── templates/
|
|
164
|
+
├── index.json
|
|
165
|
+
├── product.json
|
|
166
|
+
└── page.contact.json
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Use the theme CLI to pull the current store theme, edit its JSON locally, and push changes to a draft. This supports working in version control while keeping the dashboard theme editor as another way to manage the same theme data.
|
|
170
|
+
|
|
171
|
+
## Theme development CLI
|
|
55
172
|
|
|
56
|
-
|
|
173
|
+
The package exposes the `Osimart-theme` executable. The Osimart base theme provides npm scripts for common commands:
|
|
57
174
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
175
|
+
| Command | Purpose |
|
|
176
|
+
| --- | --- |
|
|
177
|
+
| `npm run dev` | Start a Nuxt theme development session against a store draft; saves in `theme/` are synchronized during the session. |
|
|
178
|
+
| `npm run theme:list` | List themes available to the configured store. |
|
|
179
|
+
| `npm run theme:pull` | Pull the live theme into local `theme/` files. |
|
|
180
|
+
| `npm run theme:pull -- --theme <id>` | Pull a specific theme by ID. |
|
|
181
|
+
| `npm run theme:push` | Push local theme files to a draft theme. |
|
|
182
|
+
| `npm run theme:push -- --theme live` | Push directly to the live theme. Use with care. |
|
|
183
|
+
| `npx Osimart-theme publish <id>` | Make the specified theme live. |
|
|
64
184
|
|
|
65
|
-
|
|
185
|
+
The CLI also supports `--dry-run`, `--force`, and `--prune` on push, and `--delete` on pull. Run `npx Osimart-theme` to print its usage. A normal push checks whether the remote theme changed since the last pull; pull and reconcile those edits before pushing, or use `--force` when intentionally replacing the remote version.
|
|
66
186
|
|
|
67
|
-
|
|
68
|
-
key, a component's props or a route changes.
|
|
69
|
-
2. `git tag v1.4.0 && git push --tags` → `release.yml` publishes to GitHub Packages and sends
|
|
70
|
-
`storefront-release` to every repo in `STORE_REPOS`; each one updates and redeploys.
|
|
187
|
+
## Customizing platform behavior
|
|
71
188
|
|
|
72
|
-
|
|
73
|
-
theme repos), variable `STORE_REPOS` (`ositcom/osimart-theme-base ositcom/store-offsiders`).
|
|
74
|
-
Package settings: *Manage Actions access* → every theme repo; *Manage access* → each outside
|
|
75
|
-
developer (read).
|
|
189
|
+
If you are developing this package itself, shared behavior lives under `app/logic`, reusable platform UI under `app/components`, and shared Nuxt/Vue behavior under `app/composables`, `app/services`, and `app/stores`. Prefer changing shared logic here when the behavior should apply to all Osimart themes. Prefer changing a theme's Vue/CSS when the change is visual or unique to one storefront.
|
|
76
190
|
|
|
77
|
-
|
|
191
|
+
Inside this Nuxt layer, avoid `~/` imports because `~` resolves to the consuming theme. Use:
|
|
192
|
+
|
|
193
|
+
- `#osi/...` for this package's app files, such as composables and services.
|
|
194
|
+
- `#logic/...` for shared section and component logic.
|
|
195
|
+
- `#components` when using components that a theme may override.
|
|
196
|
+
|
|
197
|
+
Treat component props, emitted events, routes, and the objects returned by `useLogic` as public integration points. Update theme consumers when changing those contracts.
|
|
198
|
+
|
|
199
|
+
## Package development and releases
|
|
200
|
+
|
|
201
|
+
To work on a theme and a local copy of this package together, link the package into the theme project, then run the theme's development command. For example, from the theme project:
|
|
78
202
|
|
|
79
203
|
```bash
|
|
80
|
-
|
|
204
|
+
npm link ../osimart-storefront
|
|
205
|
+
npm run dev
|
|
81
206
|
```
|
|
207
|
+
|
|
208
|
+
Package releases use semantic versioning. Compatible fixes and additions should preserve existing theme APIs; breaking changes to public component props, routes, or logic return values should be treated as major changes. Theme projects can update the dependency with their package manager and then rebuild/redeploy through their normal Osimart deployment process.
|
|
209
|
+
|
|
210
|
+
## More information
|
|
211
|
+
|
|
212
|
+
- [Osimart theme development API](./THEME_DEV_API.md) — endpoints and payloads used by the theme CLI.
|
|
213
|
+
- The Osimart base theme README — theme project setup, theme file structure, deployment, and theme-specific customization examples.
|
package/package.json
CHANGED