clean up and standardize READMEs (#185)

* clean up and standardize READMEs * Update packages/docs-site/README.md Co-authored-by: Phil Miller <[email protected]> * add changeset --------- Co-authored-by: Theo Ephraim <[email protected]>
dmno-dev · Dec 25, 2024 · 29dcfc2 · 29dcfc2
1 parent 68b7f01
commit 29dcfc2
Show file tree

Hide file tree

Showing 17 changed files with 318 additions and 69 deletions.
diff --git a/.changeset/warm-tools-raise.md b/.changeset/warm-tools-raise.md
@@ -0,0 +1,18 @@
+---
+"@dmno/encrypted-vault-plugin": patch
+"@dmno/fastify-integration": patch
+"@dmno/cloudflare-platform": patch
+"@dmno/nextjs-integration": patch
+"@dmno/astro-integration": patch
+"@dmno/remix-integration": patch
+"@dmno/vite-integration": patch
+"@dmno/netlify-platform": patch
+"@dmno/1password-plugin": patch
+"@dmno/bitwarden-plugin": patch
+"@dmno/infisical-plugin": patch
+"@dmno/vercel-platform": patch
+"@dmno/configraph": patch
+"dmno": patch
+---
+
+update readmes
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@ npx dmno init
 
 Check out the [docs](https://dmno.dev/docs) for more information on [plugins](https://dmno.dev/docs/plugins/overview/), [integrations](https://dmno.dev/docs/integrations/overview/), and [platforms](https://dmno.dev/docs/platforms/overview/) we support.
 
-🚧 We're currently in beta, so if you notice anything weird or there's a feature you would like to see, definitely let us know here on GitHub or on [Discord](https://chat.dmno.dev). 🚧
+> If you notice anything weird or there's a feature you would like to see, let us know here on [GitHub](https://github.com/dmno-dev/dmno/issues/new/choose) or on [Discord](https://chat.dmno.dev).
 
 
 ## Contributing

diff --git a/packages/configraph/README.md b/packages/configraph/README.md
@@ -2,8 +2,8 @@
 
 This library powers the reactive graph at the core of [DMNO](https://dmno.dev).
 
-It is designed to be able to use on its own (outside of DMNO), but is not ready for external use just yet.
+It will eventually be released as a standalone library, but we're still actively iterating on it.
 
-*** THIS IS PREVIEW SOFTWARE AND SUBJECT TO RAPID CHANGE ***
+If you're interested in using `configraph` or have any questions, please reach out to us on [Discord](https://chat.dmno.dev).
 
-If you have any questions, please reach out to us on [Discord](https://chat.dmno.dev).
+For more information on DMNO in general, please see the [DMNO docs](https://dmno.dev/docs).
diff --git a/packages/core/README.md b/packages/core/README.md
@@ -1,9 +1,7 @@
 # DMNO Core [![npm](https://img.shields.io/npm/v/dmno?label=dmno)](https://www.npmjs.com/package/dmno)
 
-Welcome to `dmno` (core) which powers `dmno`, and currently includes the config engine, CLI, and associated tools. 
+Welcome to `dmno` core which powers `dmno`, and currently includes the config engine, CLI, and associated tools. 
 
 Check out the [docs](https://dmno.dev/docs) for more information on how to use DMNO.
 
-*** THIS IS PREVIEW SOFTWARE AND SUBJECT TO RAPID CHANGE ***
-
 If you have any questions, please reach out to us on [Discord](https://chat.dmno.dev).
diff --git a/packages/docs-site/README.md b/packages/docs-site/README.md
@@ -1,9 +1,6 @@
 > If you're looking for this site in a browser, you can find it at [dmno.dev](https://dmno.dev).
 
-# DMNO Docs (dmno.dev)
-
-Start by following the instructions in the [root README](../../README.md) to install dependencies and get started.
-
+# DMNO Docs - dmno.dev
 
 ## 🚀 Project Structure
 
@@ -29,6 +26,7 @@ All commands are run from the root of the project, from a terminal:
 | `pnpm run preview`         | Preview your build locally, before deploying     |
 | `pnpm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
 | `pnpm run astro -- --help` | Get help using the Astro CLI                     |
+| `pnpm run -w build:libs`          | Run at root to build the libraries for the docs site            |
 
 ## 👀 Want to learn more?
 

diff --git a/packages/integrations/astro/README.md b/packages/integrations/astro/README.md
@@ -1,6 +1,5 @@
 Check out the [docs](https://dmno.dev/docs/integrations/astro/) for more information on how to use [DMNO](https://dmno.dev) + [Astro](https://astro.build/).
 
-*** THIS IS PREVIEW SOFTWARE AND SUBJECT TO RAPID CHANGE ***
 
 If you have any questions, please reach out to us on [Discord](https://chat.dmno.dev).
 
@@ -10,7 +9,19 @@ If you have any questions, please reach out to us on [Discord](https://chat.dmno
 
 Provides tooling to integrate dmno into your astro dev/build workflow
 
-### How to use
+### Installation
+
+```bash
+# let dmno init do the work for you
+npx dmno init
+```
+
+```bash
+# or do it manually
+npm add @dmno/astro-integration
+```
+
+### Example Usage
 
 Import and initialize our astro integration and add to the integrations section in your astro.config.mjs file
 
@@ -27,11 +38,4 @@ export default defineConfig({
 ```
 
 
-add type references to `src/env.d.ts`
-
-```
-/// <reference types="../.dmno/.typegen/global-public.d.ts" />
-```
-
-
 
diff --git a/packages/integrations/fastify/README.md b/packages/integrations/fastify/README.md
@@ -1,16 +1,20 @@
 Check out the [docs](https://dmno.dev/docs/integrations/fastify/) for more information on how to use [DMNO](https://dmno.dev) + [Fastify](https://fastify.dev/).
 
-*** THIS IS PREVIEW SOFTWARE AND SUBJECT TO RAPID CHANGE ***
-
 If you have any questions, please reach out to us on [Discord](https://chat.dmno.dev).
 
 ----
 
 # @dmno/fastify-integration [![npm](https://img.shields.io/npm/v/@dmno/fastify-integration)](https://www.npmjs.com/package/@dmno/fastify-integration)
 
-Provides tooling to integrate dmno into your fastify app
+Provides tooling to integrate DMNO into your Fastify app
+
+### Installation
+
+```bash
+npm add @dmno/fastify-integration
+```
 
-### How to use
+### Example Usage
 
 Import and register the `dmnoFastifyPlugin` when you initialize Fastify.
 

diff --git a/packages/integrations/nextjs/README.md b/packages/integrations/nextjs/README.md
@@ -1,7 +1,5 @@
 Check out the [docs](https://dmno.dev/docs/integrations/nextjs/) for more information on how to use [DMNO](https://dmno.dev) + [Next.js](https://nextjs.org/).
 
-*** THIS IS PREVIEW SOFTWARE AND SUBJECT TO RAPID CHANGE ***
-
 If you have any questions, please reach out to us on [Discord](https://chat.dmno.dev).
 
 ----
@@ -10,9 +8,19 @@ If you have any questions, please reach out to us on [Discord](https://chat.dmno
 
 Provides tooling to integrate dmno into your nextjs app
 
-### How to use
+  ### Installation
+
+```bash
+# let dmno init do the work for you
+npx dmno init
+```
+
+```bash
+# or do it manually
+npm add @dmno/nextjs-integration
+```
 
-#### Add to your next config
+### Example Usage
 
 Initialize the plugin and use in your next config (`next.config.mjs`)
 
@@ -38,7 +46,18 @@ import '@dmno/nextjs-integration';
 ```
 
 
-### Gotchas
+#### Add to package.json
 
-Running `dmno run -w -- next dev` will automatically restart the next dev server on config changes, but unfortunately it does not trigger a page refresh in the browser
+```json
+{
+  "name": "yourapp",
+  "scripts": {
+    "dev": "dmno run -w -- next dev",
+    "build": "dmno run -- next build",
+    "start": "dmno run -- next start",
+    "lint": "dmno run -- next lint"
+  },
+  // ...
+}
+```
 
diff --git a/packages/integrations/remix/README.md b/packages/integrations/remix/README.md
@@ -1,7 +1,5 @@
 Check out the [docs](https://dmno.dev/docs/integrations/remix/) for more information on how to use [DMNO](https://dmno.dev) + [Remix](https://remix.run/).
 
-*** THIS IS PREVIEW SOFTWARE AND SUBJECT TO RAPID CHANGE ***
-
 If you have any questions, please reach out to us on [Discord](https://chat.dmno.dev).
 
 ----
@@ -10,10 +8,22 @@ If you have any questions, please reach out to us on [Discord](https://chat.dmno
 
 Provides tooling to integrate dmno into your Remix dev/build workflow
 
-### How to use
+### Installation
+
+```bash 
+# let dmno init automatically add the integration
+npx dmno init
+```
+
+```bash
+# or do it manually
+npm add @dmno/remix-integration
+```
+
+### Example Usage
 
 Import and initialize our remix integration and add to your `vite.config.ts` file.
-You must add both the vite plugin and the Remix preset.
+You must add both the Vite plugin and the Remix preset.
 
 ```typescript
 import { dmnoRemixVitePlugin, dmnoRemixPreset } from "@dmno/remix-integration";

diff --git a/packages/integrations/vite/README.md b/packages/integrations/vite/README.md
@@ -1,18 +1,30 @@
 Check out the [docs](https://dmno.dev/docs/integrations/vite/) for more information on how to use [DMNO](https://dmno.dev) + [Vite](https://vitejs.dev/).
 
-*** THIS IS PREVIEW SOFTWARE AND SUBJECT TO RAPID CHANGE ***
-
 If you have any questions, please reach out to us on [Discord](https://chat.dmno.dev).
 
 ----
 
 # @dmno/vite-integration [![npm](https://img.shields.io/npm/v/@dmno/vite-integration)](https://www.npmjs.com/package/@dmno/vite-integration)
 
-Provides tooling to integrate dmno into your vite dev/build workflow
+Provides tooling to integrate `dmno` into your Vite dev/build workflow
+
+## How to use
 
-### How to use
+### Installation
 
-Import and initialize our vite plugin and add to the plugins section in your vite.config.ts file
+```bash
+# let dmno init do the work for you
+npx dmno init
+```
+
+```bash
+# or do it manually
+npm add @dmno/vite-integration
+```
+
+### Usage
+
+Import and initialize our Vite plugin and add to the plugins section in your `vite.config.ts` file
 
 ```typescript
 import { dmnoViteIntegration } from '@dmno/vite-integration';
@@ -28,5 +40,3 @@ export default defineConfig({
 
 });
 ```
-
-
diff --git a/packages/platforms/cloudflare/README.md b/packages/platforms/cloudflare/README.md
@@ -1,9 +1,76 @@
 Check out the [docs](https://dmno.dev/docs/platforms/cloudflare/) for more information on how to use [DMNO](https://dmno.dev) with [Cloudflare](https://cloudflare.com/).
 
-*** THIS IS PREVIEW SOFTWARE AND SUBJECT TO RAPID CHANGE ***
-
 If you have any questions, please reach out to us on [Discord](https://chat.dmno.dev).
 
 ----
 
 # @dmno/cloudflare-platform [![npm](https://img.shields.io/npm/v/@dmno/cloudflare-platform)](https://www.npmjs.com/package/@dmno/cloudflare-platform)
+
+### Installation
+
+```bash
+npm add @dmno/cloudflare-platform
+```
+
+### Example Usage
+
+```typescript
+import { CloudflareWranglerEnvSchema, DmnoWranglerEnvSchema } from '@dmno/cloudflare-platform';
+import { OnePasswordDmnoPlugin } from '@dmno/1password-plugin';
+import {
+  DmnoBaseTypes, defineDmnoService, pickFromSchemaObject, switchBy,
+} from 'dmno';
+
+// initialize our 1Password plugin
+const opSecrets = new OnePasswordDmnoPlugin('1pass', {
+  fallbackToCliBasedAuth: true,
+});
+
+export default defineDmnoService({
+  schema: {
+    // config that affects wrangler directly
+    ...pickFromSchemaObject(CloudflareWranglerEnvSchema, {
+      CLOUDFLARE_ACCOUNT_ID: {
+        value: opSecrets.itemByReference('op://Shared/Cloudflare/account id'),
+      },
+      CLOUDFLARE_API_TOKEN: {
+        value: opSecrets.itemByReference('op://Shared/Cloudflare/workers api token'),
+      },
+    }),
+
+    // special config that controls wrangler via `dwrangler` cli wrapper (all optional)
+    ...pickFromSchemaObject(DmnoWranglerEnvSchema, {
+      WRANGLER_ENV: {}, // passed as --env
+      WRANGLER_DEV_IP: { value: 'custom.host.local' }, // passed as --ip
+      WRANGLER_DEV_PORT: { value: 8881 }, // passed as --port
+      WRANGLER_DEV_URL: {}, // will be populated with full dev URL
+      WRANGLER_LIVE_RELOAD: { value: true }, // passed as `--live-reload`
+      WRANGLER_DEV_ACTIVE: {}, // true when running `dwrangler dev` or `dwrangler pages dev`
+      WRANGLER_BUILD_ACTIVE: {}, // true when dwrangler is performing a build for deployment
+    }),
+
+    // ... rest of your app config
+    SOME_VAR: {
+      value: switchBy('WRANGLER_DEV_ACTIVE', { // use info from wrangler to affect other config
+        _default: 'dev value',
+        false: 'prod value',
+      }),
+    },
+  },
+});
+```
+
+### `dwrangler` wrapper
+
+Our Cloudflare platform integration also provides a thin wrapper called `dwrangler` that injects the config into the `wrangler` cli. In most cases, you can just use `dwrangler` in your package.json scripts instead of `wrangler`.
+
+```json
+{
+  "scripts": {
+    "dev": "dwrangler dev",
+    "deploy": "dwrangler deploy"
+  }
+}
+```
+
+> Read more about the `dwrangler` wrapper and all the additional features DMNO unlocks in the [docs](https://dmno.dev/docs/platforms/cloudflare/).
diff --git a/packages/platforms/netlify/README.md b/packages/platforms/netlify/README.md
@@ -1,9 +1,36 @@
 Check out the [docs](https://dmno.dev/docs/platforms/netlify/) for more information on how to use [DMNO](https://dmno.dev) with [Netlify](https://netlify.com/).
 
-*** THIS IS PREVIEW SOFTWARE AND SUBJECT TO RAPID CHANGE ***
-
 If you have any questions, please reach out to us on [Discord](https://chat.dmno.dev).
 
 ----
 
 # @dmno/netlify-platform [![npm](https://img.shields.io/npm/v/@dmno/netlify-platform)](https://www.npmjs.com/package/@dmno/netlify-platform)
+
+This package provides a set of prebuilt types and environment variables for Netlify.
+
+## Installation
+
+```bash
+npm add @dmno/netlify-platform
+```
+
+### Example Usage
+
+```typescript
+import { defineDmnoService, switchBy, pickFromSchemaObject } from 'dmno';
+import { NetlifyEnvSchema } from '@dmno/netlify-platform/types';
+
+export default defineDmnoService({
+  schema: {
+    ...pickFromSchemaObject(NetlifyEnvSchema, 'CONTEXT', 'BUILD_ID'),
+    APP_ENV: {
+      value: switchBy('CONTEXT', {
+        _default: 'local',
+        'deploy-preview': 'staging',
+        'branch-deploy': 'staging',
+        production: 'production',
+      }),
+    },
+  },
+});
+```