Skip to main content
Version: v2

Migrating from v1 to v2

This page is the step-by-step checklist for moving an existing modernGraphTool v1 database to v2.

Looking for the highlights?

For a feature-level overview of what's different, see What's New in v2. This page stays focused on the migration procedure.

Compatibility​

Your existing data works as-is. The folder structure and file formats are unchanged:

  • phone_book.json — same structure, same location (data/phone_book.json)
  • FR measurement files — same .txt format in data/phones/
  • Target curve files — same .txt format in data/target/
  • Preference Bound files — Bounds U.txt / Bounds D.txt still .txt, but their location changed (see Migration Steps below — moved from v1's extensions/preference-bound/data/ to data/)

config.js retains the same general structure. All v1 settings (INITIAL_PHONES, INITIAL_TARGETS, NORMALIZATION, VISUALIZATION, INTERFACE, PATH, WATERMARK, TARGET_MANIFEST, etc.) remain compatible. v2 adds a few optional new sections — see What's New in v2.

Deployment is also the same — v2 outputs a fully static SPA to dist/. Copy the folder to your web server. The .htaccess file for Apache SPA fallback is included.

Migration Steps​

  1. Download the latest v2 release.

  2. Copy your data — Move your data/ folder (phones, targets, phone_book.json) into the v2 release folder.

  3. Move Preference Bound data files — In v1, Bounds U.txt and Bounds D.txt lived in extensions/preference-bound/data/. In v2 they must sit directly in data/, alongside phones/ and target/. If you skip this, the Preference Bound overlay will silently fail to render when enabled. The base DF target file (e.g. KEMAR DF (KB006x) Target.txt) should already be in data/target/ as part of step 2.

  4. Migrate config.js — Copy your v1 config.js settings into the v2 config.js template. The core settings are the same; review the new sections (SQUIGLINK, TARGET_CUSTOMIZER, PREFERENCE_BOUND, SAMPLES, CDN_MODE) and adjust as needed. The old MULTI_SAMPLE and HPTF sections are still read for compatibility, but SAMPLES replaces both — convert them while you are here. You can use the Config Editor to easily migrate and review all settings; it does the SAMPLES conversion for you.

  5. Migrate theme.css — If you customized theme.css, port your color values to the v2 format (CSS custom properties for graph styling, plus OKLCH-based UI variables). The Theme Generator can help.

  6. Migrate page metadata (index.html) — v2 ships with its own index.html, so any edits you made to your v1 index.html do not carry over automatically. Re-apply them in the v2 index.html:

    • <title> and <meta name="title">
    • <meta name="description"> and <meta name="keywords">
    • Open Graph tags: <meta property="og:title">, <meta property="og:description">, <meta property="og:url">, <meta property="og:image">
    • <link rel="canonical">
    • Favicons: <link rel="icon">, <link rel="shortcut icon">, <link rel="apple-touch-icon">
    • <meta name="apple-mobile-web-app-title">
    • Web app manifest: <link rel="manifest"> (if you had one)

    The Customizing the Page → Changing Page Metadata section has the field-by-field reference.

    Source builders

    If you build from source, edit src/app.html instead of index.html. The output dist/index.html is generated from that template.

  7. Delete extensions — The extensions/ folder is no longer used. Any extension settings should now be in config.js.

  8. Test locally — Open the page in a browser and verify your data loads correctly.

Picking a Deployment Option​

v1 shipped as a pre-built drop — you downloaded a release, uploaded it, and that was the only path. v2 adds three more:

  • Pre-built Release — The one-for-one replacement for your v1 setup. Download the release, copy your data and config in, upload. No surprises, no BASE_PATH to set, works exactly like v1 did.
  • CDN Deployment — Recommended, and a thinner drop: only your index.html, config.js, theme.css, data/, and assets/ live on your server; the app bundle itself loads from jsDelivr and auto-updates.
  • GitHub Pages — CDN deployment hosted on GitHub for free, if you'd rather not keep running a web server for this.
  • Building from Source — For developers and forks.
CDN Alternative

Instead of hosting the full pre-built release, consider the CDN deployment mode. You don't need to manage the app code, and future updates apply automatically with it.

If you pick CDN mode, watch out for BASE_PATH​

In v2 CDN mode, any deployment not at the root of its (sub)domain requires CDN_MODE.BASE_PATH in config.js. Without it, the home page loads fine but every share link 404s. The fix is one config line. For a site at example.com/headphones/:

CDN_MODE: {
  MAJOR_VERSION: 2,
  BASE_PATH: "/headphones",
},

Full explanation and worked examples: Why BASE_PATH is almost always required.

squig.link operators typically run two instances on the same subdomain: <username>.squig.link/ for earphones (at the subdomain root — no BASE_PATH) and <username>.squig.link/headphones/ for headphones (needs BASE_PATH: "/headphones"). Each instance has its own config.js, so set BASE_PATH only on the /headphones/ one. The root earphones instance stays as-is.

Personal databases under a subdirectory like example.com/headphones/ need BASE_PATH to match. A database at example.com/ (domain root) does not.

Switching between CDN and pre-built later​

Everything that isn't the app bundle itself (data, config, theme, Preference Bound files) is identical between the two options. You can switch back and forth by swapping your index.html file and optionally adding or removing the CDN_MODE section from config.js. There's no lock-in.