npm - electrobun - Versions diffs - 0.0.1 → 0.0.3 - Mend

electrobun 0.0.1 → 0.0.3

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 (729) hide show

package/documentation/docs/guides/Getting Started/Creating UI.md ADDED Viewed

@@ -0,0 +1,147 @@
+---
+sidebar_position: 3
+title: Creating UI
+sidebar_label: 3. Creating UI
+---
+:::info
+Continuing on from the [Hello World](/docs/guides/Getting%20Started/Hello%20World) Guide we're going to add some UI.
+:::
+Currently our app is opening a browser window and just loading a url. Let's make a simple web browser.
+Let's create a new folder `src/main-ui/` and add an index file. This is where our browser code will go. The Electrobun cli will automatically transpile this into javascript and make it available at the url `views://main-ui/index.js`
+```typescript title="src/main-ui/index.ts
+import { Electroview } from "electrobun/view";
+// Instantiate the electrobun browser api
+const electrobun = new Electroview({ rpc: null });
+window.loadPage = () => {
+  const newUrl = document.querySelector("#urlInput").value;
+  const webview = document.querySelector(".webview");
+  webview.src = newUrl;
+};
+window.goBack = () => {
+  const webview = document.querySelector(".webview");
+  webview.goBack();
+};
+window.goForward = () => {
+  const webview = document.querySelector(".webview");
+  webview.goForward();
+};
+```
+Let's create an html file to load into the BrowserView that will load the transpiled javascript above:
+```html title="src/main-ui/index.html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>My Web Browser</title>
+    <script src="views://main-ui/index.js"></script>
+</head>
+<body>
+    <h1>My Web Browser</h1>
+    <input type="text" id="urlInput" placeholder="Enter URL">
+    <button onclick="loadPage()">Go</button>
+    <button onclick="goBack()">Back</button>
+    <button onclick="goForward()">Forward</button>
+    <electrobun-webview class="webview" width="100%" height="100%" src="https://electrobun.dev">
+</body>
+</html>
+```
+Now let's update our `electrobun.config` file so that it knows to transpile the new typescript and html files for our main-ui:
+```javascript title="electrobun.config"
+{
+  "app": {
+    "name": "My App",
+    "identifier": "dev.my.app",
+    "version": "0.0.1"
+  },
+  "build": {
+    "bun": {
+      "entrypoint": "src/bun/index.ts"
+    },
+    "views": {
+        "main-ui": {
+            "entrypoint": "src/main-ui/index.ts"
+        }
+    },
+    "copy": {
+        "src/main-ui/index.html": "views/main-ui/index.html"
+    }
+  }
+}
+```
+And finally let's update our bun process code to load the new html file:
+```typescript title="src/bun/index.ts"
+import { BrowserWindow } from "electrobun/bun";
+const win = new BrowserWindow({
+  title: "Hello Electrobun",
+  url: "views://main-ui/index.html",
+});
+```
+Now back in terminal `ctrl+c` if it was running and then `bun start` to rebuild and launch. You should now see a window with an input, type in `https://google.com` and hit go, then try the back and forward buttons.
+You'll notice that while you can right click on the text input and choose copy and paste from the default context menu. `cmd+c` and `cmd+v` as well as `cmd+a` to select all don't work. Let's update our main bun file to set up an Application Edit menu to enable those keyboard shortcuts.
+```typescript title="src/bun/index.ts"
+import { BrowserWindow, ApplicationMenu } from "electrobun/bun";
+ApplicationMenu.setApplicationMenu([
+  {
+    submenu: [{ label: "Quit", role: "quit" }],
+  },
+  {
+    label: "Edit",
+    submenu: [
+      { role: "undo" },
+      { role: "redo" },
+      { type: "separator" },
+      {
+        label: "Custom Menu Item  🚀",
+        action: "custom-action-1",
+        tooltip: "I'm a tooltip",
+      },
+      {
+        label: "Custom menu disabled",
+        enabled: false,
+        action: "custom-action-2",
+      },
+      { type: "separator" },
+      { role: "cut" },
+      { role: "copy" },
+      { role: "paste" },
+      { role: "pasteAndMatchStyle" },
+      { role: "delete" },
+      { role: "selectAll" },
+    ],
+  },
+]);
+const win = new BrowserWindow({
+  title: "Hello Electrobun",
+  url: "views://main-ui/index.html",
+});
+```
+You'll notice now that when the app is focused your app now has an Edit menu, and because we used `role:` for the `cut`, `copy`, `paste`, and `selectAll` menu items those global keyboard shortcuts will now work in your app's url input.
+:::info Congratulations
+You just built a simple web browser in Electrobun!
+:::

package/documentation/docs/guides/Getting Started/Distributing.md ADDED Viewed

@@ -0,0 +1,116 @@
+---
+sidebar_position: 4
+title: Distributing
+sidebar_label: 4. Distributing
+---
+:::info
+Continuing on from the [Creating UI](/docs/guides/Getting%20Started/Creating%20UI) Guide.
+:::
+Let's add two more scripts to our `package.json` file to get our app ready for distribution. `build:canary` and `build:stable`:
+```json title="package.json
+{
+  "name": "my-app",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "electrobun": "^0.0.1"
+  },
+  "scripts": {
+    "start": "bun run build:dev && electrobun dev",
+    "build:dev": "bun install && electrobun build",
+    "build:canary": "electrobun build env=canary",
+    "build:stable": "electrobun build env=stable"
+  }
+}
+```
+In your terminal you can now run
+```
+bun run build:canary
+// or
+bun run build:stable
+```
+Both of these non-dev builds will:
+- build an optimized MacOS app bundle
+- tar and compress it using state of the art compression
+- generate another self-extracting app bundle
+- create an `artifacts` folder for distribution
+:::info
+All you need to distribute your app is a static file host like S3 or Google Cloud Storage. There's no need to run a server beyond that.
+:::
+Let's assume you've set up a Google Cloud Storage bucket with a subfolder for this application and add it to `electrobun.config`:
+```json title="electrobun.config"
+{
+  "app": {
+    "name": "My App",
+    "identifier": "dev.my.app",
+    "version": "0.0.1"
+  },
+  "build": {
+    "bun": {
+      "entrypoint": "src/bun/index.ts"
+    },
+    "views": {
+      "main-ui": {
+        "entrypoint": "src/main-ui/index.ts"
+      }
+    },
+    "copy": {
+      "src/main-ui/index.html": "views/main-ui/index.html"
+    }
+  },
+  "release": {
+    "bucketUrl": "https://storage.googleapis.com/mybucketname/myapp/"
+  }
+}
+```
+You can make your app available by simply uploading the contents of the `artifacts` folder into the `myapp` folder of your bucket. The artifacts folder will have two subfolders, one for `canary` and one for `stable`.
+Once you've uploaded the artifacts to your bucket when your run a non-dev build command again like `bun run build:canary` the Electrobun cli will automatically download the current version of your app, use our custom optimize BSDIFF implementation to generate a patch file and add the patch file to your artifacts folder.
+Visit the [Updater API docs](/docs/apis/bun/Updater) to learn how to make your app check for and install updates.
+### What are all the files in the artifacts folder
+```
+// Assuming your app's name is MyApp and you did a canary build you'll have the following files:
+// This file contains metadata for the version of your app you just built
+/artifacts/canary/update.json
+// This is the file you would link to on your marketing site for users to download
+// when first installing your app. It's a dmg that contains your app in its
+// self-extracting form
+/artifacts/canary/MyApp-canary.dmg
+// This is a copy of the compressed tar file of your app bundle. There's a copy
+// of this inside the self-extracting bundle. When your app updates itself if there
+// are no patch files available it will download this to update your app.
+/artifacts/canary/MyApp-canary.app.tar.zst
+// These files are named <hash>.patch. The Electrobun cli generates patch files
+// from the current version on your static cloud hosting to the version your just
+// built.
+// When replacing the contents of your static file host you can keep as many old
+// patch files as you like. Users with older versions of your app will keep downloading
+// the next patch automatically when updating.
+/artifacts/canary/jsf87yasf.patch
+```

package/documentation/docs/guides/Getting Started/Getting Started.md ADDED Viewed

@@ -0,0 +1,7 @@
+---
+sidebar_position: 1
+---
+This Getting Started guide will give you an overview of Electrobun.
+It'll guide you through creating a simple hello world app all the way from setting up your project to distributing it.

package/documentation/docs/guides/Getting Started/Hello World.md ADDED Viewed

@@ -0,0 +1,93 @@
+---
+sidebar_position: 2
+title: Hello World
+sidebar_label: 2. Hello World
+---
+:::info
+Electrobun will install a specific version of bun as a dependency in `node_modules`.
+:::
+:::info
+This guide assumes you have bun installed globally, if you're using node.js or another package manager then you may need to adjust the terminal commands and package.json scripts accordingly.
+:::
+## Step 1: Initialize your project folder
+Create a new folder for your project. Let's call it `/electrobun-test`.
+In your `electrobun-test` folder run `bun init .` You'll be prompted to enter a package name, let's use `my-app` and an entrypoint which we don't need so just hit enter.
+## Step 2: Install Electrobun as a dependency
+Let's install electrobun. Just run: `bun install electrobun` to add it as a dependency.
+## Step 3: Add package.json scripts to build and run your app
+Open your `package.json` in a code editor and add a build:dev script and a start script so that your `package.json` looks like this:
+```json title="package.json"
+{
+  "name": "my-app",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "electrobun": "^0.0.1"
+  },
+  "scripts": {
+    "start": "bun run build:dev && electrobun dev",
+    "build:dev": "bun install && electrobun build"
+  }
+}
+```
+:::note
+That we've modified the default package.json that bun creates
+- Removed the "type": "module" and "module": "index.ts" properties since we don't need them.
+- Added two npm scripts that will use the electrobun cli that should now be in your node_modules/.bin folder.
+  :::
+## Step 4: Hello World
+We now have electrobun installed and a way to build and run our hello world app, let's add some code.
+Create a file in `src/bun/index.ts` with the following contents:
+```typescript title="src/bun/index.ts"
+import { BrowserWindow } from "electrobun/bun";
+const win = new BrowserWindow({
+  title: "Hello Electrobun",
+  url: "https://electrobun.dev",
+});
+```
+## Step 5: Configure Electrobun
+One last thing, we need to a way to let the Electrobun cli know where our bun entrypoint file is and how to build it. We do that by creating an electrobun.config file in the root of the project.
+```json title="electrobun.config"
+{
+  "app": {
+    "name": "My App",
+    "identifier": "dev.my.app",
+    "version": "0.0.1"
+  },
+  "build": {
+    "bun": {
+      "entrypoint": "src/bun/index.ts"
+    }
+  }
+}
+```
+## Step 6: Run your app
+With this we can now go back to our terminal and run `bun start` and you should see a window pop up and load the site.
+To stop running the app just hit `cmd+c`

package/documentation/docs/guides/Getting Started/What is Electrobun.md ADDED Viewed

@@ -0,0 +1,39 @@
+---
+sidebar_position: 1
+title: What is Electrobun
+sidebar_label: 1. What is Electrobun
+---
+Electrobun aims to be a batteries included framework for building desktop apps with Typescript.
+## Priorities
+What makes electrobun different, aside from our approach to achitecture are our project goals:
+### Batteries included
+- Write typescript without waisting time on devops
+- Everything needed to build, test, codesign, update
+### Iteration speed
+- Building your app as fast as possible so you can iterate on features and fixes as fast as possible
+- Enabling you to ship small, cost effective updates (as small as 14KB) so you can ship new features and fixes to your end users and get feedback as fast and often as possible
+### Affordable to maintain
+- MIT open source
+- Ship updates to your users that are tiny
+- All you need is a file server (eg: S3) to distribute your app
+### Flexible
+- Use any modern framework for UI (from plain HTML, to Preact, SolidJS, and more)
+- Use the built-in system Webview (or bundle a 3rd party webview like Chromium: _coming soon..._)
+### Security and Performance
+- Bun and Zig under the hood
+- The main process and browser processes are isolated from each other
+- Opt-in to enable fast, typed, and easy to extend RPC between main and browser processes
+- A custom webview tag implementation for OOPIFs so you can build a web browser

package/documentation/docs/guides/Guides/Using Tailwind ADDED Viewed

File without changes

package/documentation/docusaurus.config.ts ADDED Viewed

@@ -0,0 +1,153 @@
+import { themes as prismThemes } from "prism-react-renderer";
+import type { Config } from "@docusaurus/types";
+import type * as Preset from "@docusaurus/preset-classic";
+const config: Config = {
+  title: "Electrobun",
+  tagline:
+    "Build ultra fast, tiny, and cross-platform desktop apps with Typescript",
+  favicon: "img/electrobun-logo-32.png",
+  // Set the production url of your site here
+  url: "https://electrobun.dev",
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: "/",
+  onBrokenLinks: "throw",
+  onBrokenMarkdownLinks: "warn",
+  // Even if you don't use internationalization, you can use this field to set
+  // useful metadata like html lang. For example, if your site is Chinese, you
+  // may want to replace "en" with "zh-Hans".
+  i18n: {
+    defaultLocale: "en",
+    locales: ["en"],
+  },
+  presets: [
+    [
+      "classic",
+      {
+        docs: {
+          sidebarPath: "./sidebars.ts",
+        },
+        blog: {
+          showReadingTime: true,
+          feedOptions: {
+            type: ["rss", "atom"],
+            xslt: true,
+          },
+        },
+        theme: {
+          customCss: "./src/css/custom.css",
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+  themeConfig: {
+    colorMode: {
+      defaultMode: "dark",
+      disableSwitch: false,
+      respectPrefersColorScheme: true,
+    },
+    announcementBar: {
+      id: "alpha",
+      content:
+        "Electrobun is just getting started. The API is likely to change as we build toward a stable v1",
+      backgroundColor: "#1160af",
+      textColor: "#efefef",
+      isCloseable: true,
+    },
+    // Replace with your project's social card
+    // image: "img/social-card.jpg",
+    navbar: {
+      title: "Electrobun",
+      logo: {
+        alt: "Electrobun Logo",
+        src: "img/electrobun-logo-256.png",
+      },
+      items: [
+        {
+          type: "docSidebar",
+          sidebarId: "guidesSidebar",
+          position: "left",
+          label: "Docs",
+        },
+        {
+          type: "docSidebar",
+          sidebarId: "apiSidebar",
+          position: "left",
+          label: "API Reference",
+        },
+        { to: "/blog", label: "Updates", position: "left" },
+        {
+          href: "https://github.com/blackboardsh/electrobun",
+          label: "GitHub",
+          position: "right",
+        },
+      ],
+    },
+    footer: {
+      style: "dark",
+      links: [
+        {
+          title: "Docs",
+          items: [
+            {
+              label: "Getting Started",
+              to: "/docs/guides/Getting%20Started/",
+            },
+            {
+              label: "What is Electrobun?",
+              to: "/docs/guides/Getting%20Started/What%20is%20Electrobun",
+            },
+            {
+              label: "Hello World",
+              to: "/docs/guides/Getting%20Started/Hello%20World",
+            },
+          ],
+        },
+        {
+          title: "Community",
+          items: [
+            {
+              label: "GitHub",
+              href: "https://github.com/blackboardsh/electrobun/issues",
+            },
+            {
+              label: "Discord",
+              href: "https://www.electrobun.dev/#",
+            },
+            {
+              label: "Twitter",
+              href: "https://x.com/BlackboardTech",
+            },
+            {
+              label: "Blog",
+              to: "/blog",
+            },
+          ],
+        },
+        {
+          title: "Sponsors",
+          items: [
+            {
+              label: "Blackboard Technologies Inc.",
+              href: "https://blackboard.sh",
+            },
+          ],
+        },
+      ],
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+      additionalLanguages: ["json", "typescript"],
+      defaultLanguage: "typescript",
+    },
+  } satisfies Preset.ThemeConfig,
+};
+export default config;