Skip to content

Commit 24fc4e0

Browse files
GregBrimblecourtney-sims
GregBrimble
and
courtney-sims
authored
Document support for secrets and env vars (#750)
Co-authored-by: Courtney Sims <csims@cloudflare.com>
1 parent 965e4be commit 24fc4e0

File tree

1 file changed

+56
-22
lines changed

1 file changed

+56
-22
lines changed

‎CONTRIBUTING.md‎

Lines changed: 56 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -14,23 +14,25 @@ If CI is failing on your pull request, running `pnpm run fix` in the repository
1414

1515
In order to introduce a new template to this collection, the following requirements must all be satisfied. For a boiled-down version of these requirements, scroll down to the [Checklist](#checklist).
1616

17-
### Package.json content
17+
### `package.json` content
1818

1919
Cloudflare's Templates Platform extracts `name`, `description`, and a `cloudflare` object directly from each template's `package.json` configuration. This extracted metadata provides content necessary for the template to be rendered in the Cloudflare Dashboard. If the minimally required values are not included in your template, it will fail CI.
2020

21-
| Required? | Package.json key | Description | Example |
22-
| ----------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
23-
| ✅ | `name` | Kebab-case name of your template, should match directory, should end in `-template`. | durable-chat-template |
24-
| ✅ | `description` | Brief, one-line description of the template | Chat with other users in real-time using Durable Objects and PartyKit. |
25-
| | `cloudflare` | Object you will nest all cloudflare-specific keys in | |
26-
| _if publish=true_ | `cloudflare.label` | Title Case version of name for use in Cloudflare's Dashboard | Durable Chat App |
27-
| _if publish=true_ | `cloudflare.products` | List 3 or fewer products featured in your example | ["D1", "Durable Objects"] |
28-
| ❌ | `cloudflare.categories` | String(s) that map to filter(s) in the template gallery view | ["starter", "storage"] |
29-
| _if publish=true_ | `cloudflare.preview_image_url` | 16:9 aspect screenshot of the template application | (Link will be provided during PR review) |
30-
| ❌ | `cloudflare.publish` | Boolean to opt-in for display in the Cloudflare Dashboard - leave out unless requested by the Cloudflare team | (Primarily for internal contributor use) |
31-
32-
### Best Practices: package.json
33-
21+
| Required? | Package.json key | Description | Example |
22+
| ----------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
23+
| ✅ | `name` | Kebab-case name of your template, should match directory, should end in `-template`. | durable-chat-template |
24+
| ✅ | `description` | Brief, one-line description of the template | Chat with other users in real-time using Durable Objects and PartyKit. |
25+
| | `cloudflare` | Object you will nest all cloudflare-specific keys in | |
26+
| | `cloudflare.bindings` | Object containing information about each binding. Keys should be the binding names and values should be an object with a "description" string. Inline markdown `` `code` ``, `**bold**`, `__italics__` and `[links](https://example.com/)` are valid. | ``{ "COOKIE_SIGNING_KEY": { "description": "Generate a random string using `openssl rand -hex 32`" } }`` |
27+
| _if publish=true_ | `cloudflare.label` | Title Case version of name for use in Cloudflare's Dashboard | Durable Chat App |
28+
| _if publish=true_ | `cloudflare.products` | List 3 or fewer products featured in your example | ["D1", "Durable Objects"] |
29+
| ❌ | `cloudflare.categories` | String(s) that map to filter(s) in the template gallery view | ["starter", "storage"] |
30+
| _if publish=true_ | `cloudflare.preview_image_url` | 16:9 aspect screenshot of the template application | (Link will be provided during PR review) |
31+
| ❌ | `cloudflare.publish` | Boolean to opt-in for display in the Cloudflare Dashboard - leave out unless requested by the Cloudflare team | (Primarily for internal contributor use) |
32+
33+
### Best Practices: `package.json`
34+
35+
- **`cloudflare.bindings.[bindingName].description`** - Include a description for any binding which requires additional information on how to configure, especially for any values which are found outside of Cloudflare (e.g. API keys).
3436
- **`cloudflare.products`** - Do not exceed 3 products listed. Focus on highlighting the most unique products featured in your template (e.g. majority of our templates leverage 'Worker Assets' in some capacity, but only a select few feature 'DO').
3537
- **`cloudflare.categories`**
3638
- Today, categories are optional to include. In the future, we will support filters in the templates gallery at which point this will become a new template requirement.
@@ -39,11 +41,11 @@ Cloudflare's Templates Platform extracts `name`, `description`, and a `cloudflar
3941
- Can only be provided by a Cloudflare team member. Image files for icons and preview images are stored in the Cloudflare Templates CF account.
4042
- Preview image should be a screenshot of the application running in-browser.
4143

42-
### Package-lock.json
44+
### `package-lock.json`
4345

4446
All of our templates and Deploy to Cloudflare projects automatically set up Workers CI. In our testing, including a package lock file in the template repository speeds up module resolution by 80% or more.
4547

46-
To generate a package-lock.json for your template, run this command in the root of the repository:
48+
To generate a `package-lock.json` for your template, run this command in the root of the repository:
4749

4850
```sh
4951
pnpm fix:lockfiles
@@ -72,19 +74,51 @@ This content will be included in Template Details Page
7274
This content will NOT be included in the Template Details Page
7375
```
7476

75-
### Secrets & Environment Variables
77+
### Worker secrets, environment variables, and Secrets Store secrets
7678

77-
For both secrets and environment variables, we recommend letting your users know if any configuration is missing directly in the deployed application's UI. See [this example](https://saas-admin-template.templates.workers.dev/admin) from a current template.
79+
You can create templates which use [Worker secrets](https://developers.cloudflare.com/workers/platform/environment-variables#secrets), [environment variables](https://developers.cloudflare.com/workers/configuration/environment-variables) or [Secrets Store secrets](https://developers.cloudflare.com/secrets-store/).
7880

79-
To configure application variables, follow the developer documentation for [environment variables](https://developers.cloudflare.com/workers/configuration/environment-variables) or [secrets](https://developers.cloudflare.com/workers/configuration/secrets).
81+
Although these will be configured by users during deployment, we still recommend confirming these are present and valid within your deployed application. Let your users know with a prominent warning within the deployed application's UI if anything is invalid. See [this example](https://saas-admin-template.templates.workers.dev/admin) from a current template.
8082

81-
#### Secrets
83+
#### Workers Secrets
8284

83-
Today, there is no standard way to derive the required secrets from a project’s repository. Please include a section in your ReadMe listing all required secrets for your template and where users should go to find the appropriate values.
85+
Create a `.dev.vars.example` or `.env.example` file in the root of your template repository with a [dotenv](https://www.npmjs.com/package/dotenv) format:
86+
87+
```ini
88+
COOKIE_SIGNING_KEY=my-secret # example comment: should be a real random string in production
89+
```
90+
91+
[Secrets Store](https://developers.cloudflare.com/secrets-store/) secrets can be configured in the Wrangler configuration file as normal:
92+
93+
```json
94+
{
95+
"name": "my-worker",
96+
"main": "./src/index.ts",
97+
"compatibility_date": "$today",
98+
"secrets_store_secrets": [
99+
{
100+
"binding": "API_KEY",
101+
"store_id": "demo",
102+
"secret_name": "api-key"
103+
}
104+
]
105+
}
106+
```
84107

85108
#### Environment Variables
86109

87-
Environment variables that do not require users to update them will automatically be included in the new project (e.g. `“ENVIRONMENT”: “staging”`). Variables that require user update (e.g. `“PROJECT_ID”: “[your project id]”`) will need to be configured after initial deployment.
110+
Environment variables can also be configured in the Wrangler configuration file as normal:
111+
112+
```json
113+
{
114+
"name": "my-worker",
115+
"main": "./src/index.ts",
116+
"compatibility_date": "$today",
117+
"vars": {
118+
"API_HOST": "https://example.com"
119+
}
120+
}
121+
```
88122

89123
## Playwright E2E Tests
90124

0 commit comments

Comments
 (0)