Skip to content

⚡️⚡️⚡️ Self-hosted collaborative bookmark manager to collect, read, annotate, and fully preserve what matters, all in one place.

extension: improved DX

daniel31x13caeccb377718
diff --git a/apps/extension/README.md b/apps/extension/README.md
index 104f08a5..68c09d35 100644
--- a/apps/extension/README.md
+++ b/apps/extension/README.md
@@ -65,63 +65,30 @@ yarn dev:chrome
yarn dev:firefox
```
-Either command builds the extension, launches the browser with it already installed,
-and reloads it whenever a file under `src/` changes. Both run off the same manifest
-and `dist/` folder, so there is nothing else to set up. Firefox reports that
-`background.service_worker` is ignored, which is expected: it uses
-`background.scripts` from that same manifest.
-
-The browser starts from a temporary profile, so your Linkwarden server settings are
-gone on the next start. Add `--keep-profile-changes --chromium-profile ./.profile`
-(or `--firefox-profile`) to the relevant script if you would rather keep them.
-
-To load the extension into a browser yourself, `yarn dev` runs only the watching
-build and keeps `dist/` up to date.
-
-### The manifest
-
-`manifest.config.ts` is the only manifest source. It describes one shared manifest
-plus the few keys that differ per target, and a vite plugin writes the result to
-`manifest.json` in the build output. There are two targets: `default` for the
-Chrome and Firefox build in `dist/`, and `safari` for `dist-safari/`, selected by
-the `EXT_TARGET` environment variable that `yarn build:safari` sets.
-
-Version bumps and permission changes go in that one file, Safari included: see
-[Versioning](#versioning) below. Anything Safari cannot
-do (the bookmarks permission, the service worker, the omnibox keyword) is a flag
-on the target rather than a second copy of the manifest.
-
## Safari
-Safari is built through the Xcode project in `safari/`, which is committed to this
-repository and maintained by hand.
-
```
yarn build:safari
-open safari/Linkwarden/Linkwarden.xcodeproj
```
-Then Product → Archive in Xcode.
+Then Cmd+R to run it, or Product → Archive to build for the App Store.
+
+Cmd+R launches `Linkwarden for Safari.app`. Launching it registers the extension with Safari.
+
+### First run
-The Xcode project references `dist-safari/` directly rather than holding its own copy
-of the extension, so `yarn build:safari` has to run first or you will archive a
-stale build. There is no conversion step: running `safari-web-extension-converter`
-against `safari/` would replace the committed project and its signing configuration.
+Safari hides locally built extensions until the developer settings are on:
-## Versioning
+1. Safari → Settings → Advanced → **Show features for web developers**
+2. The new Develop menu → **Allow unsigned extensions**
+3. Safari → Settings → Extensions → enable **Linkwarden**
-The version lives in `manifest.config.ts` and nowhere else. Every build writes it
-to `version.xcconfig`, which the Xcode project reads as the base configuration on
-both targets, so one edit covers Chrome, Firefox and Safari.
+Step 2 resets every time Safari restarts, so expect to repeat it. Steps 1 and 3 are
+one-time.
-`version.xcconfig` is generated and committed. Do not edit it by hand. It is
-committed rather than ignored so a fresh clone opens in Xcode without a dangling
-file reference, which would silently resolve `MARKETING_VERSION` to empty and
-produce an archive App Store Connect rejects. Any build regenerates it, so
-`git diff --exit-code apps/extension/version.xcconfig` after a build is a
-reasonable CI check that the two have not drifted.
+### Iterating
-`CURRENT_PROJECT_VERSION` also lives there. It is the build number rather than the
-version, and only has to be unique per App Store Connect upload, so CI passes
-`CURRENT_PROJECT_VERSION=$GITHUB_RUN_NUMBER` on the `xcodebuild` command line,
-which takes precedence over the xcconfig.
+There is no live reload here, unlike `yarn dev:chrome` and `yarn dev:firefox`. The
+build output is copied into the app extension at compile time, so every change to
+`src/` means `yarn build:safari` followed by another Cmd+R. Develop against Chrome or
+Firefox and use Safari to verify, rather than working in it directly.
diff --git a/apps/extension/manifest.config.ts b/apps/extension/manifest.config.ts
index 69b7ed80..07a5325c 100644
--- a/apps/extension/manifest.config.ts
+++ b/apps/extension/manifest.config.ts
@@ -56,7 +56,7 @@ const targets: Record<ManifestTarget, TargetOptions> = {
* into `version.xcconfig`, which the Xcode project reads as its base
* configuration. Bump it here and nowhere else.
*/
-export const version = "1.5.4";
+export const version = "1.5.5";
const icons = {
"16": "16.png",
diff --git a/apps/extension/package.json b/apps/extension/package.json
index e8855b81..095741b8 100644
--- a/apps/extension/package.json
+++ b/apps/extension/package.json
@@ -4,11 +4,12 @@
"version": "0.0.0",
"type": "module",
"scripts": {
- "dev": "vite build --watch",
"dev:chrome": "yarn build && concurrently -k -n build,chrome -c blue,green \"vite build --watch\" \"web-ext run --target chromium --source-dir dist\"",
"dev:firefox": "yarn build && concurrently -k -n build,firefox -c blue,magenta \"vite build --watch\" \"web-ext run --target firefox-desktop --source-dir dist\"",
+ "build:safari": "tsc && EXT_TARGET=safari vite build --outDir dist-safari && cp public/*.png dist-safari/ && node scripts/safari-next-steps.mjs",
+ "dev": "vite build --watch",
"build": "tsc && vite build",
- "build:safari": "tsc && EXT_TARGET=safari vite build --outDir dist-safari && cp public/*.png dist-safari/",
+ "bump:build": "node scripts/bump-build.mjs",
"lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
"preview": "vite preview"
},
diff --git a/apps/extension/scripts/bump-build.mjs b/apps/extension/scripts/bump-build.mjs
new file mode 100644
index 00000000..5c821b14
--- /dev/null
+++ b/apps/extension/scripts/bump-build.mjs
@@ -0,0 +1,29 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const file = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ "../version.xcconfig"
+);
+
+const source = fs.readFileSync(file, "utf8");
+const match = source.match(/^CURRENT_PROJECT_VERSION\s*=\s*(\d+)\s*$/m);
+
+if (!match) {
+ console.error(`No CURRENT_PROJECT_VERSION found in ${file}`);
+ process.exit(1);
+}
+
+const current = Number(match[1]);
+const next = current + 1;
+
+fs.writeFileSync(
+ file,
+ source.replace(match[0], `CURRENT_PROJECT_VERSION = ${next}`)
+);
+
+console.log(`Build number ${current} -> ${next}`);
+console.log(
+ "Check this is above the last build App Store Connect accepted before uploading."
+);
diff --git a/apps/extension/scripts/safari-next-steps.mjs b/apps/extension/scripts/safari-next-steps.mjs
new file mode 100644
index 00000000..5b6da275
--- /dev/null
+++ b/apps/extension/scripts/safari-next-steps.mjs
@@ -0,0 +1,11 @@
+const colour = process.stdout.isTTY && !process.env.NO_COLOR;
+const cyan = (text) => (colour ? `\x1b[36m${text}\x1b[0m` : text);
+
+console.log(
+ "Now run `open safari/Linkwarden/Linkwarden.xcodeproj` and then Cmd+R in Xcode."
+);
+console.log(
+ cyan(
+ "For submission, run `yarn bump:build` first, then in Xcode: Product → Archive, then Organizer → Distribute App → App Store Connect → Upload."
+ )
+);
diff --git a/apps/extension/version.xcconfig b/apps/extension/version.xcconfig
index ea3f89b7..3d2fb196 100644
--- a/apps/extension/version.xcconfig
+++ b/apps/extension/version.xcconfig
@@ -1,4 +1,8 @@
-// Generated from manifest.config.ts by vite.config.ts. Do not edit.
-// Bump the version in manifest.config.ts and rebuild.
-MARKETING_VERSION = 1.5.4
-CURRENT_PROJECT_VERSION = 1
+// Generated from manifest.config.ts by vite.config.ts.
+// MARKETING_VERSION is overwritten on every build: change it in
+// manifest.config.ts, not here.
+// CURRENT_PROJECT_VERSION is preserved across builds and is yours to edit.
+// Raise it before every App Store Connect upload you archive locally; it
+// must always be higher than the last build Apple accepted.
+MARKETING_VERSION = 1.5.5
+CURRENT_PROJECT_VERSION = 3
diff --git a/apps/extension/vite.config.ts b/apps/extension/vite.config.ts
index 242c92b4..e42986ca 100644
--- a/apps/extension/vite.config.ts
+++ b/apps/extension/vite.config.ts
@@ -1,52 +1,57 @@
-import fs from 'fs';
-import path from 'path';
-import react from '@vitejs/plugin-react';
-import { defineConfig, type Plugin } from 'vite';
-import { buildManifest, resolveTarget, version } from './manifest.config';
+import fs from "fs";
+import path from "path";
+import react from "@vitejs/plugin-react";
+import { defineConfig, type Plugin } from "vite";
+import { buildManifest, resolveTarget, version } from "./manifest.config";
// `build:safari` sets EXT_TARGET; every other build, including the watching dev
// builds, gets the Chrome and Firefox manifest.
const target = resolveTarget();
-const isWatch = process.argv.includes('--watch') || process.argv.includes('-w');
+const isWatch = process.argv.includes("--watch") || process.argv.includes("-w");
+
+function readBuildNumber(file: string) {
+ if (!fs.existsSync(file)) return "1";
+ const match = fs
+ .readFileSync(file, "utf8")
+ .match(/^CURRENT_PROJECT_VERSION\s*=\s*(\d+)\s*$/m);
+ return match ? match[1] : "1";
+}
-// Xcode resolves build settings before any script it could run, so the Safari
-// project cannot read manifest.config.ts. It reads this instead, as the base
-// configuration on both targets. Committed so a fresh clone opens without a
-// dangling reference, which would leave MARKETING_VERSION empty and produce an
-// archive App Store Connect rejects.
-//
-// CURRENT_PROJECT_VERSION is the build number rather than the version, and only
-// has to be unique per upload. CI overrides it on the xcodebuild command line,
-// which beats an xcconfig.
function writeVersionXcconfig() {
+ const file = path.resolve(__dirname, "version.xcconfig");
+
fs.writeFileSync(
- path.resolve(__dirname, 'version.xcconfig'),
+ file,
[
- '// Generated from manifest.config.ts by vite.config.ts. Do not edit.',
- '// Bump the version in manifest.config.ts and rebuild.',
+ "// Generated from manifest.config.ts by vite.config.ts.",
+ "// MARKETING_VERSION is overwritten on every build: change it in",
+ "// manifest.config.ts, not here.",
+ "// CURRENT_PROJECT_VERSION is preserved across builds and is yours to edit.",
+ "// Raise it before every App Store Connect upload you archive locally; it",
+ "// must always be higher than the last build Apple accepted.",
`MARKETING_VERSION = ${version}`,
- 'CURRENT_PROJECT_VERSION = 1',
- '',
- ].join('\n')
+ `CURRENT_PROJECT_VERSION = ${readBuildNumber(file)}`,
+ "",
+ ].join("\n")
);
}
// Writing the manifest here rather than copying a file afterwards keeps it in
// place for `vite build --watch`, which never returns to run a follow-up step.
function manifest(): Plugin {
- let outDir = path.resolve(__dirname, 'dist');
+ let outDir = path.resolve(__dirname, "dist");
return {
- name: 'linkwarden:manifest',
- apply: 'build',
+ name: "linkwarden:manifest",
+ apply: "build",
configResolved(config) {
outDir = path.resolve(config.root, config.build.outDir);
},
writeBundle() {
fs.writeFileSync(
- path.join(outDir, 'manifest.json'),
- JSON.stringify(buildManifest(target), null, 2) + '\n'
+ path.join(outDir, "manifest.json"),
+ JSON.stringify(buildManifest(target), null, 2) + "\n"
);
// Every target, not just safari, so the two cannot drift apart just
// because `build:safari` happened not to run.
@@ -59,7 +64,7 @@ export default defineConfig({
plugins: [react(), manifest()],
resolve: {
alias: {
- '@': path.resolve(__dirname, './src'),
+ "@": path.resolve(__dirname, "./src"),
},
},
build: {
@@ -69,12 +74,12 @@ export default defineConfig({
emptyOutDir: !isWatch,
rollupOptions: {
input: {
- main: path.resolve(__dirname, 'index.html'),
- options: path.resolve(__dirname, 'src/pages/Options/options.html'),
- background: path.resolve(__dirname, 'src/pages/Background/index.ts'),
+ main: path.resolve(__dirname, "index.html"),
+ options: path.resolve(__dirname, "src/pages/Options/options.html"),
+ background: path.resolve(__dirname, "src/pages/Background/index.ts"),
},
output: {
- entryFileNames: '[name].js',
+ entryFileNames: "[name].js",
},
},
},