@shopify/polaris-types 0.0.0-rc.1

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 (4) hide show
  1. package/README.md +154 -0
  2. package/dist/custom-elements.json +12179 -0
  3. package/dist/polaris.d.ts +7311 -0
  4. package/package.json +20 -0
package/README.md ADDED
@@ -0,0 +1,154 @@
1
+ # polaris-publish
2
+
3
+ Publishing relay for `@shopify/polaris-types` to the public npm registry.
4
+
5
+ ## Why This Exists
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.
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
+ └─────────────────────────────────────────────────────────────────────────────┘
57
+ ```
58
+
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):
80
+
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`
86
+
87
+ ## How to Release
88
+
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.
121
+
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
126
+
127
+ ### "Package already exists"
128
+
129
+ **Cause**: This exact version was already published to npm.
130
+
131
+ **Fix**: Bump the version in World and re-run the release process.
132
+
133
+ ### "Release asset not found"
134
+
135
+ **Cause**: The GitHub release was not created or the tarball was not attached.
136
+
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
141
+
142
+ ## Files
143
+
144
+ ```
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)