feat: merge pull request #38 from nyaggah/develop

feat(readme): update @bedframe/core readme
nyaggah · Jun 4, 2023 · ec24722 · ec24722
2 parents dd2a34e + d254dc8
commit ec24722
Show file tree

Hide file tree

Showing 3 changed files with 243 additions and 9 deletions.
diff --git a/.changeset/khaki-plums-kneel.md b/.changeset/khaki-plums-kneel.md
@@ -0,0 +1,5 @@
+---
+"@bedframe/core": patch
+---
+
+feat(readme): update @bedframe/core readme
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -1,7 +1,7 @@
-# # To get started with Dependabot version updates, you'll need to specify which
-# # package ecosystems to update and where the package manifests are located.
-# # Please see the documentation for all configuration options:
-# # https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
 
 version: 2
 updates:

diff --git a/packages/core/README.md b/packages/core/README.md
@@ -1,7 +1,236 @@
-# @bedframe/core
+<div>
+  >_<br />
+  <br />
+  B R O W S E R<br />
+  E X T E N S I O N<br />
+  D E V E L O P M E N T<br />
+  F R A M E W O R K<br />
+</div>
 
-This is the main Bedframe package
+#
 
-- Installation
-- Use
-- Examples
+<p align="left">
+  <a aria-label="Bedframe logo" href="https://bedframe.dev">
+    <img src="https://img.shields.io/badge/BEDFRAME-7a46fc.svg?style=for-the-badge&logo=Bedframe&labelColor=CCC">
+  </a>
+  <a aria-label="@bedframe/core - NPM version" href="https://www.npmjs.com/package/@bedframe/core">
+    <img alt="" src="https://img.shields.io/npm/v/@bedframe/core.svg?style=for-the-badge&labelColor=000000">
+  </a>
+  <a aria-label="@bedframe/cli - NPM version" href="https://www.npmjs.com/package/@bedframe/cli">
+    <img alt="" src="https://img.shields.io/npm/v/@bedframe/cli.svg?style=for-the-badge&labelColor=000000">
+  </a>
+  <a aria-label="License" href="https://github.com/nyaggah/bedframe/blob/main/LICENSE">
+    <img alt="" src="https://img.shields.io/npm/l/next.svg?style=for-the-badge&labelColor=000000">
+  </a>
+</p>
+
+#
+
+## **@bedframe/core**
+
+Your Browser Extension Development Framework (core types &amp; funcs)
+
+### Installation
+
+<blockquote>
+  <br />
+  <h4><strong>Node Version Requirement</strong></h4>  
+  Bedframe CLI requires <a href="https://nodejs.org/" target="_blank" rel="noopener noreferrer">Node.js</a> 14.18+, 16+. You can manage multiple versions of Node on the same machine with <a href="https://github.com/tj/n" target="_blank" rel="noopener noreferrer">n</a>, <a href="https://github.com/creationix/nvm" target="_blank" rel="noopener noreferrer">nvm</a> or <a href="https://github.com/coreybutler/nvm-windows" target="_blank" rel="noopener noreferrer">nvm-windows</a>.
+  <br /><br />
+</blockquote>
+
+```bash
+# with npm
+npm install @bedframe/core -D
+
+# with yarn
+yarn add @bedframe/core -D
+
+#  with pnpm
+pnpm add @bedframe/core -D
+```
+
+### Usage
+
+The best way to get started with Bedframe is by using the `create-bedframe` project generator or run the `make` command using the `@bedframe/cli`.
+
+If building a project from scratch, assuming you've generated a Vite project (w/ React + TypeScript), after installing `@beframe/core`, ensure a folder structure like the following:
+
+**The default Bedframe setup if for a Chrome Popup extension**
+
+Production-ready dev setup complete with configuration for:
+
+- tests (unit testing w/ Vitest)
+- linting & formating (w/ eslint + prettier w/ lint-staged)
+- source control (w/ git)
+  - publish/ release workflows (ci/cd w/ github actions)
+  - automated dependency updates (w/ dependapot workflows)
+  - conventional commits and git hooks (commitizen + commitlint)
+  - changesets (w/ changesets)
+    - conventional changelog
+
+```bash
+
+# Bedframe (default) project structure
+bedframe-project/
+├─ .git/
+├─ .husky/
+├─ .vscode
+├─ public/
+│  ├─ icons/
+│  │  ├─ icon-16x16.png
+│  │  ├─ icon-32x32.png
+│  │  ├─ icon-48x48.png
+│  │  ├─ icon-128x128.png
+├─ src/
+│  ├─ components/
+│  ├─ manifest/
+│  │  ├─ chrome.ts
+│  │  ├─ index.ts
+│  ├─ pages/
+│  │  ├─ popup/
+│  │  │  ├─ popup.ts
+│  │  │  ├─ popup.html
+│  │  ├─ options/
+│  │  │  ├─ options.ts
+│  │  │  ├─ options.html
+├─ vitest/
+│  ├─ vitest.setup.ts
+├─ .gitignore
+├─ LICENSE
+├─ package.json
+├─ README.md
+├─ tsconfig.ts
+├─ tsconfig.node.ts
+├─ vite.config.ts
+├─ vitest.config.ts
+```
+
+### Defining your manifest
+
+```typescript
+function createManifest(
+  manifest: Manifest, // chrome.runtime.ManifestV3
+  browser: Browser // "chrome" | "brave" | "opera" | "edge" | "firefox" | "safari"
+): BuildTarget
+```
+
+```typescript
+// types
+type Manifest = chrome.runtime.ManifestV3
+
+type Browser = 'Chrome' | 'Brave' | 'Opera' | 'Edge' | 'Firefox' | 'Safari'
+
+type BuildTarget = {
+  manifest: Manifest
+  browser: Browser
+}
+```
+
+### Usage
+
+Assuming you have a manifest for Chrome browser here `src/manifest/chrome.ts`, you'd create your manifest like so:
+
+```typescript
+
+import { createManifest } from '@bedframe/core'
+
+export chrome = createManifest({
+  // Required
+  name: "My Chrome Extension",
+  version: "0.0.1",
+  manifest_version: 3,
+
+   // Recommended
+  action: {
+    //
+  },
+  default_locale: "en",
+  description: "A plain text description",
+  icons: {...},
+},
+
+// tell vite.config which browser to target the build for
+'chrome'
+)
+
+```
+
+the `createManifest` returns an `BuildTarget` object that contains the MV3 manifest + a strin denoting what browser the manifest is for.
+
+we pass this along to the `vite.config.ts`
+
+```typescript
+import { resolve } from 'node:path'
+import { defineConfig } from 'vite'
+import { crx } from '@crxjs/vite-plugin'
+import react from '@vitejs/plugin-react'
+import { getManifest } from '@bedframe/core'
+import * as manifest from './src/manifest'
+
+export default ({ mode }) => {
+  return defineConfig({
+    resolve: {
+      alias: {
+        '@': resolve(__dirname, './src'),
+      },
+    },
+    plugins: [
+      react(),
+      crx({
+        manifest: getManifest(mode, [manifest.chrome]),
+      }),
+    ],
+    build: {
+      outDir: `dist/${mode}`,
+    },
+  })
+}
+```
+
+ensure you have a script to dev in local and build (for production), etc like so:
+
+```json
+// package.json
+{
+  // other fields...
+  "scripts": {
+    "dev": "vite --mode chrome",
+    "build": "tsc && vite build --mode chrome",
+    "preview": "vite preview",
+    "build:extension-chrome": "vite build --mode chrome",
+    "build:all": "concurrently yarn:build:extension-*"
+  }
+  // other fields...
+}
+```
+
+now when we run
+
+```bash
+npm run build
+```
+
+the extension for chrome will be built and output in the `dist/` folder:
+
+```bash
+# Output for you chrome extension
+dist/
+├─ chrome/
+│  ├─ assets/
+│  ├─ icons/
+│  ├─ manifest.json
+│  ├─ service-worker-loader.js
+```
+
+### Load in Chrome
+
+load unpacked from dist/chrome
+
+### Developing w/ Bedframe
+
+npm run dev
+npm run build (watch ?)
+
+- HMR
+- etc