@shopify/polaris-types 0.0.0-rc.1 → 0.0.0-rc.2

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.
Files changed (2) hide show
  1. package/README.md +30 -135
  2. package/package.json +3 -2
package/README.md CHANGED
@@ -1,154 +1,49 @@
1
- # polaris-publish
1
+ # @shopify/polaris-types
2
2
 
3
- Publishing relay for `@shopify/polaris-types` to the public npm registry.
3
+ Type definitions for [Polaris web components](https://shopify.dev/docs/api/app-home/polaris-web-components).
4
4
 
5
- ## Why This Exists
5
+ ## Installation
6
6
 
7
- The `@shopify/polaris-types` package source lives in [shop/world](https://github.com/shop/world) (private repo). Publishing to the public npm registry requires [OIDC Trusted Publishers](https://docs.npmjs.com/generating-provenance-statements#publishing-packages-with-provenance-via-github-actions), which has specific requirements that World alone cannot satisfy.
7
+ Add the types package as a dev dependency:
8
8
 
9
- This repo acts as a **publishing relay**:
10
-
11
- - World builds the tarball and creates a GitHub release with the asset
12
- - World sends a `repository_dispatch` event to trigger this repo's publish workflow
13
- - This repo downloads the tarball and publishes to npm using OIDC
14
-
15
- ### Cross-Repo Auth: polaris-types-publish GitHub App
16
-
17
- We use a **GitHub App** (`polaris-types-publish`) to authenticate cross-repository actions between `shop/world` (Shopify org) and `shopify-playground/polaris-publish`.
18
-
19
- The app itself has **no webhooks or custom logic** — it simply needs to be installed on both repositories so its generated installation token can:
20
-
21
- - **Upload release assets** to `shopify-playground/polaris-publish`
22
- - **Send `repository_dispatch`** events to trigger the publish workflow
23
-
24
- A GitHub App token (as opposed to a PAT) can be scoped to specific repositories and permissions, is not tied to a personal account, and can authenticate actions across the two orgs (`shop` and `shopify-playground`).
25
-
26
- ## Architecture
27
-
28
- ```
29
- ┌─────────────────────────────────────────────────────────────────────────────┐
30
- │ RELEASE FLOW │
31
- ├─────────────────────────────────────────────────────────────────────────────┤
32
- │ │
33
- │ shop/world (private) shopify-playground/polaris-publish │
34
- │ ──────────────────── ────────────────────────────────── │
35
- │ │
36
- │ 1. Changesets bumps version │
37
- │ │ │
38
- │ ▼ │
39
- │ 2. pnpm build && pnpm pack │
40
- │ │ │
41
- │ ▼ │
42
- │ 3. gh release create ──────────────► Release asset uploaded │
43
- │ │ │ │
44
- │ ▼ ▼ │
45
- │ 4. repository_dispatch ────────────► 5. Workflow triggered │
46
- │ │ │
47
- │ ▼ │
48
- │ 6. Download tarball │
49
- │ │ │
50
- │ ▼ │
51
- │ 7. npm publish (OIDC) │
52
- │ │ │
53
- │ ▼ │
54
- │ 8. Published to npmjs.org ✓ │
55
- │ │
56
- └─────────────────────────────────────────────────────────────────────────────┘
9
+ ```bash
10
+ npm i -D @shopify/polaris-types
57
11
  ```
58
12
 
59
- ## Prerequisites
60
-
61
- ### 1. polaris-types-publish GitHub App
62
-
63
- The `polaris-types-publish` GitHub App must be installed on **both** repositories:
64
-
65
- - `shop/world`
66
- - `shopify-playground/polaris-publish`
67
-
68
- The app requires the following permissions:
69
-
70
- | Permission | Access | Purpose |
71
- | ------------ | ---------- | --------------------------------------------------- |
72
- | Contents | Read/Write | Upload release assets to this repo |
73
- | Actions | Write | Send `repository_dispatch` events to trigger publish |
74
-
75
- In the World workflow, generate an installation token using the app's credentials (App ID + private key stored as secrets) and use it for the `gh release create` and `repository_dispatch` steps.
76
-
77
- ### 2. npm OIDC Trusted Publisher
78
-
79
- Request in [#help-eng-infrastructure](https://shopify.slack.com/archives/C01MXHNTT4Z):
13
+ ## Usage
80
14
 
81
- > Please configure npm Trusted Publisher for:
82
- >
83
- > - **Package**: `@shopify/polaris-types`
84
- > - **Repository**: `shopify-playground/polaris-publish`
85
- > - **Workflow**: `publish-polaris-types.yml`
15
+ Since Polaris web components are not imported directly, you need to add the types to your TypeScript configuration in one of the following ways:
86
16
 
87
- ## How to Release
17
+ ### Method 1: Add to tsconfig.json
88
18
 
89
- ### Step 1: Build and Upload (World)
90
-
91
- 1. Make changes to polaris-types in World
92
- 2. Run `dev changeset` and select `@shopify/polaris-types`
93
- 3. Create PR and merge
94
- 4. The "Version Packages" PR will be created/updated automatically
95
- 5. Review and merge the Version Packages PR
96
- 6. The release workflow runs automatically:
97
- - Builds and packs the tarball
98
- - Creates a GitHub release on `shopify-playground/polaris-publish` with the tarball attached
99
- - Sends a `repository_dispatch` event to trigger the publish workflow
100
-
101
- ### Step 2: Publish to npm (This Repo — Automatic)
102
-
103
- Once World sends the `repository_dispatch`, this repo's workflow automatically:
104
-
105
- 1. Downloads the tarball from the GitHub release
106
- 2. Publishes to npmjs.org via OIDC
107
-
108
- No manual intervention is needed. Check the [Actions tab](../../actions) to monitor progress.
109
-
110
- ## Troubleshooting
111
-
112
- ### "OIDC token exchange error" (npm)
113
-
114
- **Cause**: npm Trusted Publisher not configured for this repo/workflow.
115
-
116
- **Fix**: Request OIDC setup in #help-eng-infrastructure.
117
-
118
- ### "Bad credentials" or "Resource not accessible by integration"
119
-
120
- **Cause**: The `polaris-types-publish` GitHub App is not installed on one or both repos, or its permissions are insufficient.
19
+ ```json
20
+ {
21
+ "compilerOptions": {
22
+ "types": ["@shopify/polaris-types"]
23
+ }
24
+ }
25
+ ```
121
26
 
122
- **Fix**:
123
- 1. Verify the app is installed on both `shop/world` and `shopify-playground/polaris-publish`
124
- 2. Check the app has `Contents: Read/Write` and `Actions: Write` permissions
125
- 3. Verify the App ID and private key secrets are correctly configured in World
27
+ ### Method 2: Add as a triple-slash reference
126
28
 
127
- ### "Package already exists"
29
+ Add the following line at the top of your TypeScript files where you need the types:
128
30
 
129
- **Cause**: This exact version was already published to npm.
31
+ ```typescript
32
+ /// <reference types="@shopify/polaris-types" />
33
+ ```
130
34
 
131
- **Fix**: Bump the version in World and re-run the release process.
35
+ ## Custom Elements Manifest
132
36
 
133
- ### "Release asset not found"
37
+ This package includes a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) (`custom-elements.json`) that describes the Polaris web components in a standardized format. The manifest is generated using [`@custom-elements-manifest/analyzer`](https://github.com/open-wc/custom-elements-manifest) with custom Polaris plugins.
134
38
 
135
- **Cause**: The GitHub release was not created or the tarball was not attached.
39
+ IDE extensions and other tooling that understand the CEM format can use this to provide autocomplete, documentation, and other rich features for Polaris web components.
136
40
 
137
- **Fix**:
138
- 1. Check the World release workflow completed successfully
139
- 2. Verify the release exists on this repo's [Releases page](../../releases)
140
- 3. Confirm the tarball is listed as a release asset
41
+ ### Accessing the manifest
141
42
 
142
- ## Files
43
+ ```javascript
44
+ // Via package.json "customElements" field (recommended for tooling)
45
+ // The field points to: ./dist/custom-elements.json
143
46
 
47
+ // Via direct import
48
+ import cem from "@shopify/polaris-types/custom-elements";
144
49
  ```
145
- .github/workflows/
146
- └── publish-polaris-types.yml # Downloads release asset, publishes to npm via OIDC
147
- ```
148
-
149
- ## Related Links
150
-
151
- - [World polaris-types source](https://github.com/shop/world/tree/main/libraries/javascript/polaris/polaris-types)
152
- - [World release workflow](https://github.com/shop/world/blob/main/.github/workflows/libraries-javascript-polaris_release-polaris-types.yml)
153
- - [@shopify/polaris-types on npm](https://www.npmjs.com/package/@shopify/polaris-types)
154
- - [npm Trusted Publishers docs](https://docs.npmjs.com/generating-provenance-statements)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shopify/polaris-types",
3
- "version": "0.0.0-rc.1",
3
+ "version": "0.0.0-rc.2",
4
4
  "private": false,
5
5
  "publishConfig": {
6
6
  "registry": "https://registry.npmjs.org",
@@ -16,5 +16,6 @@
16
16
  },
17
17
  "files": [
18
18
  "dist"
19
- ]
19
+ ],
20
+ "packageManager": "pnpm@11.0.0"
20
21
  }