maxmntl

Neovim: Save folds in markdown files

Maximilien Monteil — Fri, 06 Feb 2026 00:00:00 GMT

Neovim: Save folds in markdown files

This is a short little TIL with Neovim

I wanted to have the lines I collapse in markdown files stay collapsed after closing the file.

Most of the solution was in this StackExchange answer.

I then make some tweaks for my personal use case:

-- ~/.config/nvim/ftplugin/markdown.lua
vim.opt_local.foldmethod = 'manual'

local folds_augroup = vim.api.nvim_create_augroup('Folds', { clear = true })

vim.api.nvim_create_autocmd(
  {'BufWritePost', 'QuitPre'},
  { group = folds_augroup, command = 'mkview' })

vim.api.nvim_create_autocmd(
  'BufWinEnter',
  { group = folds_augroup, command = 'silent! loadview | normal! zM' })

</details>

I'm entering this new era of life where the stuff I like to use needs to be as open to tinkering as possible.

I gush about having a blog so much because it brings into my life a little personal thing that I can tinker and play with exactly how I want.

With each point of contact, I can encounter a new situation that isn't quite how I want it, then pop open the hood and tune it to my exact specification.

No payment or subscription, no new contract to sign, no personal information sent to some ad service.

That's also why Neovim is so cool.

I'll go into Neovim in more detail at some other time, today I wanted to write about yet another moment where I deepened my understanding of my tool and made it more perfect for me. </section>

About Neovim

Neovim (and vim) is a modal editor.

This means, unlike text editors like VSCode and Google docs, you can't just start typing away as soon as the page is open to you.

With Neovim, you start off in "Normal" mode. How I understand it, here what you type serves to run commands on the editor itself.

For example, typing :vs will split your window in 2 vertically. <label for="quitting" class="margin-toggle">⊕</label> <input type="checkbox" id="quitting" class="margin-toggle"/> <span class="marginnote"> Obligatory <br> :q! will exit vim without saving. <br> :xa will save all and exit vim. </span>

Pressing i will then enter Insert mode where you can type like normal. Esc will then bring you back to Normal mode where you could for example delete a whole paragraph and paste it at the top. <label for="arcane-spell" class="margin-toggle">⊕</label> <input type="checkbox" id="arcane-spell" class="margin-toggle"/> <span class="marginnote"> Delete paragraph and paste it at the top: dapggP <br> - dap: delete aaround paragraph <br> - gg: go to gtop (okay it doesn't always fit) <br> - P: Paste above (versus lowercase p for paste below) </span>

It's pretty arcane and when I started out it was a pain, but the nerdy coolness hacker vibes kept me going. You may have noticed so far we haven't had to click anywhere. Well Neovim is pretty mouse free.

Now is this actually more efficient?

Personally it felt so, and it's fun solving these mini puzzles when you wanna do something in as few keystrokes as possible. The best vimmers are likely faster than someone doing the same thing with a mouse and multiple cursors. But even that depends.

Whatever you use, if you take the time to know it, you'll likely end up as fast as anything else.

One last command: zf36j

z fold (doesn't match but see how a "z" kinds looks like a fold? hehe)
f create (z is already fold so this could have been ff or zz for example)
36j 36 lines down

This will collapse the next 36 lines (plus the one you're on) into one line. Folding it neatly away.

I don't use it often, but it's practical in markdown files where I write notes.

The problem is these folds aren't automatically saved so when you quit vim and come back, everything is expanded again.

Lets change that. </section>

Feature Spec

What I want is to automatically save and restore the folds I make but only in "markdown" files.

This is all possible in Neovim's configuration which thankfully uses a full programming language instead of JSON or something worse like YAML. <label for="yaml-hater" class="margin-toggle">⊕</label> <input type="checkbox" id="yaml-hater" class="margin-toggle"/> <span class="marginnote"> Yes, that's right. I have no love in me for yaml. </span>

With Neovim your config can be written in Lua.

Which, despite having array indices that start at 1, is a very nice language I've grown to appreciate.

Neovim's API is fully accessible through Lua and so you can have it do almost whatever you want.

Autocommands

<div class="epigraph"> <blockquote> <p>You can specify commands to be executed automatically when reading or writing a file, when entering or leaving a buffer or window, and when exiting Vim.</p> <footer><a href="https://neovim.io/doc/user/autocmd.html">Autocmd - Neovim Docs</a></footer> </blockquote> </div>

This is what we want, when I'm in a markdown file, automatically save and restore folds.

Now I didn't know how to do this exactly so big thanks to Vivian De Smedt for the StackExchange answer copied (as is tradition) below:

-- First a group to keep related auto commands together
local folds_augroup = vim.api.nvim_create_augroup("Folds", { clear=true })

-- "BufWritePost": after saving the file
vim.api.nvim_create_autocmd("BufWritePost", {
    -- include this auto command in the group
    group = folds_augroup,
    -- "mkview" save the folds
    -- "filetype detect" have vim detect the kind of file we're in
    -- "set foldmethod=manual" set the kind of folding used in this
    --    file as manual instead of auto on indent
    command = "mkview | filetype detect | set foldmethod=manual"
})

-- "QuitPre": just before quitting vim
vim.api.nvim_create_autocmd("QuitPre", {
    group = folds_augroup,
    command = "mkview | filetype detect | set foldmethod=manual"
})

-- "BufWinEnter": when entering a window
vim.api.nvim_create_autocmd("BufWinEnter", {
    group = folds_augroup,
    -- "silent! loadview" load the folds without announcing anything
    -- same as above
    -- "normal! zM" in Normal mode, execute `zM`
    --    which closes all the folds just loaded
    command = "silent! loadview | filetype detect | set foldmethod=manual | normal! zM"
})

Pasting this into my config and saving then worked as advertised!

I can fold up my files just how I want and when I come back, so do they.

But that isn't exactly what I want, and if I just copy paste, what would I learn? </section>

Into the wild

First off I want this only in markdown files, and I want to use the Neovim API as much as possible. Another cool thing I discovered, if you're making some plugin exclusively for a particular filetype, Neovim has a special folder for them: ftplugin

You can have it at either of

.config/nvim/ftplugin/markdown.lua
.config/nvim/after/ftplugin/markdown.lua
- if you want your plugin to run last

-- I only want manual folding, omit this if you prefer
-- Being in the markdown ftplugin, I set it locally to the current window
vim.opt_local.foldmethod = 'manual'

local folds_augroup = vim.api.nvim_create_augroup('Folds', { clear = true })

-- you can give an auto command multiple events
vim.api.nvim_create_autocmd({'BufWritePost', 'QuitPre'}, {
  group = folds_augroup,
  command = 'mkview',
})

vim.api.nvim_create_autocmd('BufWinEnter', {
  group = folds_augroup,
  command = 'silent! loadview | normal! zM',
})

</section>

Conclusion

And with that my editor is even more perfect. <label for="meta-curse" class="margin-toggle">⊕</label> <input type="checkbox" id="meta-curse" class="margin-toggle"/> <span class="marginnote"> And the Meta Blog Post Curse is lifted!!!! </span>

Tweaked to perfection. The fact that this is even possible to this degree is reason enough to love Neovim.

If you wanted to try something similar I hope it helped you out and I hope you're a bit more interested in Neovim and other tools that give you back control.

Resources

The Making Of: maxmntl

Maximilien Monteil — Wed, 04 Feb 2026 00:00:00 GMT

The Meta Blog Post

This is it, the one you've all been waiting for, the meta post.

Not that Meta! This meta.

The blog post about the blog itself.

This will go by fast, there will be nothing surprising, but at the end you'll know.

You'll know the answer to that burning question of yours. The one gnawing at the edge of your soul...

My my! What a wonderful little blog!

So exquisite, such taste, that lettering, the theme switcher jiggle.

How on God's green earth was such an achievement of my species even possible?! <footer>Your soul.</footer>

Well my dear, beautiful reader, let's not dally any longer. <label for="interrobang-punct" class="margin-toggle">⊕</label> <input type="checkbox" id="interrobang-punct" class="margin-toggle"/> <span class="marginnote"> The "?!" above is called an interrobang. The more you know. <br> I think about that every time I write it, for the correct order. <br> Like thinking out "b-e-a-utiful". Every time. </span> </section>

Inspiration

Let's start at the very beginning.

~I was born on a Thursday~

Wait no. Or actually?

Yes, it was Thursday. I was born on a Thursday, and my first thought was:

I need a blog.

I must write. Existence has impressed upon me the futility and ephemerality of life. I must put words upon a medium that exists outside of me.

But by the time I was old enough to do something about it, I had forgotten everything.

You see, no one remembers anything from when they were a baby. </section>

Years later...

Decades even!

I was on vacation in beautiful Colombia.

Taking in the unblemished sights of the beaches of Tayrona.

As the waves calmly bobbed me and my turquoise mermaid floaty up and down, I pondered, nay I introspected

I need a blog.

For yes, how could the world continue spinning without my champagne thoughts written out, almost black on almost white. <label for="almost" class="margin-toggle">⊕</label> <input type="checkbox" id="almost" class="margin-toggle"/> <span class="marginnote">Or almost white on almost black, did you see that jiggle?!</span>

So one evening, awake in bed, the last free evening before resuming gainful employment which started at 3 am because of the time differences and also it was currently 8 pm and I should have been sleeping but revenge is so sweet when served with bedtime procrastination.

I set out to make 2 second old me proud.

I made a blog.

And now, here's how I made a blog... </section>

ugh fine if you really must know

I read a lot of Hacker News and one day someone shared Tufte CSS.

I immediately loved the style and saved that browser tab in the pile for later.

Then, on that fateful evening, I had the presence of mind to require near 0 Javascript for a static site that serves text. <label for="jiggle-last" class="margin-toggle">⊕</label> <input type="checkbox" id="jiggle-last" class="margin-toggle"/> <span class="marginnote">Except for that theme switcher, what can you do ¯\_(ツ)_/¯</span>

So I chose Astro which I'd heard a lot about but never used.

They even have a blog tutorial, fated as it was. For the sake of pragmatism and learning I just went along with it.

Then I did some SVG shenanigans for the favicon.

After that I added the theme switcher, did I mention that already?

Since then, as I write more I've edited and expanded the Tufte CSS styles to better suit my style. Which is the coolest thing ever, like a carpenter improving their tools. <label for="techward-css" class="margin-toggle">⊕</label> <input type="checkbox" id="techward-css" class="margin-toggle"/> <span class="marginnote"> Those style changes, which internally I call "Techward CSS" are here. </span>

You can find the blog's repo here. <label for="personal-void" class="margin-toggle">⊕</label> <input type="checkbox" id="personal-void" class="margin-toggle"/> <span class="marginnote">Do not look at the commits. That's my own personal screaming void.</span>

That's about it.

I knew I had to care as little as possible about how the blog is made because the point is what's written here, not how.

Now I just need to make sure to have another post after this one, lest the "curse of the meta blog" strike me and turn this blog dusty. </section>

Account Optional Apps with PowerSync

Maximilien Monteil — Tue, 03 Feb 2026 00:00:00 GMT

Account Optional Apps with PowerSync

<p class="subtitle">Local-first is cool. PowerSync is local-first. Therefore, PowerSync is cool. CQFD.</p>

Now lets look at the proof.

~What follows is a mathematical proof that local-first is in fact "cool".~

I'll go over a brief intro of local-first and introduce PowerSync, a library that helps you build apps that don't require a constant internet connection.

I argue that in the spirit of local-first, you shouldn't require an account from users.

Once convinced, I'll go through the implementation details to enable users to create data without an account and then transfer that into their account if they register or log in. </details>

First, we need some definitions.

Local-first

Local-first software is a growing movement and pattern in software development aiming to bring back the Good Old Days when you downloaded an app, it was fast, and it worked without internet and your data was all yours to do with what you want.

It's a more modern take on that with some modern amenities for the way we work now where internet is at least expected so that you can access your data on multiple devices, work with other people and more.

The best place to start learning more is with the Seven Ideals for local-first software by the Ink and Switch lab who coined the term and played a principal role in its spread.

More about local-first

PowerSync

A large part of what makes modern local-first software lies in the sync-engine.

Cause in order to have an experience that works offline, you need all your data accessible on your device locally. But to then access it on other devices or work collaboratively with others, some version of it needs to be on someone else's server.

This version needs to stay up to date with your local changes, some kind of code, machine, or engine needs to be in charge of doing the sync.

You can write your own which Linear did or you can use something like PowerSync.

PowerSync will let you have a SQLite database in your user's browser against which you can manage all their created data while in the background it'll handle syncing your changes to a remote Postgres database (, MongoDB, MySQL, or SQL Server).

It also works for pretty much any web or native client framework as well. </section>

Local-first means you shouldn't require an account

What's not to love about local-first, <label for="local-first-shots" class="margin-toggle">⊕</label> <input type="checkbox" id="local-first-shots" class="margin-toggle"/> <span class="marginnote"> Damn, take a shot everytime you read "local-first". </span> apps will load and behave instantly, you don't need to be constantly connected, your data is all yours without having to fight a corporate (purposefully?) obtuse export system, and even if the original service dies, you can keep chugging along.

All while keeping modern benefits like sync and collaboration.

I wanted that and more for my app so when I took local-first further, I realized I don't even need to require users to make an account.

After downloading the app, all your data is there, if you don't need or want to sync then there's no point in having an account. That shouldn't limit you otherwise it goes against ideal 7: "You retain ultimate ownership and control". <label for="free-users" class="margin-toggle">⊕</label> <input type="checkbox" id="free-users" class="margin-toggle"/> <span class="marginnote"> Another benefit of not requiring an account is that it's then cheaper to run the app. You can have a majority of users able to use your app without it costing you in auth seats if you use a paid service, or in DB space since sync is off. </span>

That should still apply after making an account of course, but why not without too?

So with these values in mind, I set out to update my app such that you can use the full suite of features without an account. Then when you want sync or some account-requiring feature you can choose to make one while keeping all your data. </section>

The setup

Tech here will be PowerSync of course, and Vue.

A critical resource was PowerSync's own React Supabase Todolist with Optional Sync example which set the foundation I worked off of. I recommend going over the README.md there for an explanation of how it works.

Additionally I'll go over issues and other things I ran into.

Rough Steps <label for="option-function" class="margin-toggle">⊕</label>

<input type="checkbox" id="option-function" class="margin-toggle"/> <span class="marginnote"> The [Sidebar] topics are more about the app and business logic steps, not PowerSync directly. </span>

Change your PowerSync schema creation into a function with dynamic names
Keep track when Sync Mode is enabled or not
[Sidebar]: Update your routes and UX around the auth and "user setting" pages
[Sidebar]: Handle the "signed out user"
[Sidebar]: Add a reference to the User ID in all columns if not present
The rest of the owl

Once again, we'll be referring to PowerSync's own example on how to do this quite a lot.

We've got our plan, lets get to it! </section>

Function-able Schema

We start of simple by just making sure our schema is built with a function that can take one argument.

By default, PowerSync recommends defining your tables at the top-level then passing them into new Schema like so:

const todos = new Table(
  { /* table columns */ },
  { /* table options */ },
)

const lists = new Table({ /* list of columns */ });

export const AppSchema = new Schema({
  todos,
  lists,
})

But we'll need to create our schema with dynamic view names, depending on whether we're in sync mode or not.

First we create an object for our table definitions. <label for="option-is-function" class="margin-toggle">⊕</label> <input type="checkbox" id="option-is-function" class="margin-toggle"/> <span class="marginnote">⚠ Watch out! options is a function.</span>

const todosDef = {
  columns: { /* table columns */ },
  options: (viewName: string, localOnly = false) => ({
    viewName,
    localOnly,
    /* other table options */
  }),
}

columns hasn't changed.

options is now a function, this was to avoid having to pass the same table options key value pairs so often.

This here comes straight from the example. These functions set the correct table view names depending on the sync mode we're in. We can set whatever view name we want, but know that this will be the way to reference these tables in all your queries.

function syncedName(table: string, synced: boolean) {
  return synced ? table : `inactive_synced_${table}`
}

function localName(table: string, synced: boolean) {
  return synced ? `inactive_local_${table}` : table
}

Finally there's the actual schema creation: <label for="curry-function" class="margin-toggle">⊕</label> <input type="checkbox" id="curry-function" class="margin-toggle"/> <span class="marginnote"> toSyncedName & toLocalName are other examples of lazyness. I didn't want to type the same thing out too much. <br><br> I also set the default argument value here to true since we haven't set up anything else yet. This way everything should still continue to work. </span>

export function makeSchema(synced = true) {
  const toSyncedName = (table: string) => syncedName(table, synced)
  const toLocalName = (table: string) => localName(table, synced)

  return new Schema({
    lists: new Table(
      listsDef.columns,
      listsDef.options(toSyncedName('lists')),
    ),
    local_lists: new Table(
      listsDef.columns,
      listsDef.options(toLocalName('lists'), true),
    ),

    todos: new Table(
      todosDef.columns,
      todosDef.options(toSyncedName('todos')),
    ),
    local_todos: new Table(
      todosDef.columns,
      todosDef.options(toLocalName('todos'), true),
    ),

    /* Local only draft tables */
    draft_todos: new Table(
      todosDef.columns,
      todosDef.options('draft_todos', true),
    ),
  })
}

Of special note here is the draft_todos table. This is a table that will always be local only, I don't want to sync it and in my app the logic already always clears it out. I used these draft_ tables for long running forms. Copy the live data into a draft table, apply user edits to it, then on save reconcile the changes. With this pattern I had an easier time dropping all changes on quit or cancel. <label for="repetition" class="margin-toggle">⊕</label> <input type="checkbox" id="repetition" class="margin-toggle"/> <span class="marginnote"> <br><br> Now in spite of my lazyness, there's still a ungodly amount of repetition in this schema definition. It nags at me in the night. It should be possible to have this all in a loop or so while keeping the types but I haven't gotten around to it yet. </span>

<details> <summary><h3>Here's the full thing all together</h3></summary>

const listsDef = {
  columns: { /* table columns */ },
  options: (viewName: string, localOnly = false) => ({
    viewName,
    localOnly,
  }),
}

const todosDef = {
  columns: { /* table columns */ },
  options: (viewName: string, localOnly = false) => ({
    viewName,
    localOnly,
    /* other table options */
  }),
}

function syncedName(table: string, synced: boolean) {
  return synced ? table : `inactive_synced_${table}`
}

function localName(table: string, synced: boolean) {
  return synced ? `inactive_local_${table}` : table
}

export function makeSchema(synced = true) {
  const toSyncedName = (table: string) => syncedName(table, synced)
  const toLocalName = (table: string) => localName(table, synced)

  return new Schema({
    lists: new Table(
      listsDef.columns,
      listsDef.options(toSyncedName('lists')),
    ),
    local_lists: new Table(
      listsDef.columns,
      listsDef.options(toLocalName('lists'), true),
    ),

    todos: new Table(
      todosDef.columns,
      todosDef.options(toSyncedName('todos')),
    ),
    local_todos: new Table(
      todosDef.columns,
      todosDef.options(toLocalName('todos'), true),
    ),

    /* Local only draft tables */
    draft_todos: new Table(
      todosDef.columns,
      todosDef.options('draft_todos', true),
    ),
  })
}

</details>

Finally, make sure to update the creation of your PowerSync instance with the new schema as a function.

// default to `true` so the current app keeps working
const syncEnabled = true

export const powersync = new PowerSyncDatabase({
  schema: makeSchema(syncEnabled),
  database: new WASQLiteOpenFactory({ dbFilename: DB_NAME }),
})

<details> <summary><h3>Bonus: Types</h3></summary>

To get access to the type of your database and tables you can use the following:

import type { makeSchema } from '/path/to/your/schema'

export type Database = ReturnType<typeof makeSchema>['types']
export type Tables = keyof Database

export type TodosRecord = Database['todos']
export type ListsRecord = Database['lists']

</details> </section>

Sync Mode Tracking

Your schema is now ready to work fully offline or with sync depending on the auth status.

But like with site themes, your app needs to know the auth state as early as possible for correct bootstrap and outside of the normal auth flow so that it can always be accessed.

That's a job for localStorage.

Luckily the PowerSync example has just what we need so we can copy that over.

const SYNC_KEY = 'syncEnabled'

export function getSyncEnabled(dbName: string) {
  const key = `${SYNC_KEY}-${dbName}`
  const value = JSON.parse(localStorage.getItem(key) ?? 'null') as boolean | null

  if (value == null) {
    // the example has a bug here, pass the `dbName` not the key
    // otherwise you'll get `${key}-${key}-${dbName}` stored
    setSyncEnabled(dbName, false)
    return false
  }

  return value === true
}

export function setSyncEnabled(dbName: string, enabled: boolean) {
  const key = `${SYNC_KEY}-${dbName}`

  localStorage.setItem(key, enabled ? 'true' : 'false')
}

We can then put that to good use in a few places.

PowerSync instance

import { getSyncEnabled, setSyncEnabled } from '/path/to/syncmode'

// Not the final resting place of this line
setSyncEnabled(DB_NAME, true)

const syncEnabled = getSyncEnabled(DB_NAME)

export const powersync = new PowerSyncDatabase({
  schema: makeSchema(syncEnabled),
  database: new WASQLiteOpenFactory({ dbFilename: DB_NAME }),
})

`main.ts`

This may look a bit weird, <label for="peak-performance" class="margin-toggle">⊕</label> <input type="checkbox" id="peak-performance" class="margin-toggle"/> <span class="marginnote"> This is what peak performance looks like. Not me fighting the linter (shoutout to Antfu's ESLint Config). </span> but I want to avoid a top level await (even though really this is the same thing).

import { getSyncEnabled } from '/path/to/syncmode'

async function bootstrap() {
  await powersync.init()

  const connector = new PowersyncConnector(auth)
  connector.registerListener({
    // user is signed in when this is called
    sessionStarted: async (user) => {
      // STUB for now
      const isSyncMode = getSyncEnabled(powersync.database.name)
      console.warn('[TODO]: use sync mode')

      // Only connect PowerSync to Supabase when there's a signed in user
      await powersync.connect(connector)
    },
  })

  await connector.init()
}

void bootstrap().then(() => {
  const app = createApp(App)

  app.use(router)
  app.use(store)
  app.mount('#app')
})

In the PowersyncConnector class, you'll need to register the listener and call it as needed.

// In my case I'm using Firebase for auth, if you use Supabase
// it should be more similar to the PowerSync docs.
// If you use something else this should help you find the
// places to change when using a 3rd party auth service
import type { Auth, User } from 'firebase/auth'

type ConnectorListener = {
  sessionStarted: (user: User) => Promise<void>
}

export class PowersyncConnector
  extends BaseObserver<ConnectorListener>
  implements PowerSyncBackendConnector {
  readonly sbClient: SupabaseClient

  ready: boolean

  auth: Auth

  constructor(auth: Auth) {
    super()

    this.ready = false

    this.auth = auth

    this.sbClient = createClient(
      config.supabaseUrl,
      config.supabaseAnonKey,
      {
        accessToken: async () =>
          (await this.auth.currentUser?.getIdToken(false)) ?? null,
      },
    )

    auth.onAuthStateChanged(user => this.updateUser(user))
  }

  async init() {
    if (this.ready)
      return

    await this.auth.authStateReady()
    this.updateUser(this.auth.currentUser)

    this.ready = true
  }

  updateUser(user: User | null) {
    if (user)
      this.iterateListeners(async cb => cb.sessionStarted?.(user))
  }

  // rest of the connector...
}

</section>

Sidebar: Auth Routes and Pages

On my journey to support account free usage, there were also UX and Business Logic things to change.

This may or may not apply to you but I bring it up here for completeness.

There are 2 main things you need to consider.

1. Route redirection on "auth only" pages

Like me, you probably had some pages that were meant to be accessible only to authenticated users like User Settings, or element creation, etc.

Maybe even with a cheeky route.meta.requiresAuth.

Well no longer. Now everything is accessible to everyone.

So make sure your router redirects for these pages is updated to allow visits and remove the requiresAuth route meta (or your equivalent) everywhere.

You may also want to update your catch all route. For me if someone visited /something/thats-not-a/route, I would redirect to the account sign up page. That no longer makes sense and is now the app homepage.

2. Unauthenticated user pages

Finally, the User Settings page used to only be worth it for a logged in user.

Well no longer!

People without an account may visit this page (or not, you could keep that one locked), it's worth having a version for logged out users.

I went with the Log in & Sign up buttons that link to the respective pages plus an explanation of the point of an account.

An account is optional.

Mylo is free to use without an account for as long as you want.

Logging in or creating an account lets you sync your workouts across devices.

All your workouts and training data will be merged into your account. You won't lose anything. <footer>The wording I've got on my Account page for signed out users.</footer>

</section>

Sidebar: Default Signed-Out User

This once again depends on your particular application.

If you have a user table, you're likely referencing it in a few other tables and places.

Logged out users don't have a "user" but codewise you'll want to include some logic to create a type of default user.

Most important is giving it a User ID which you'll need to reference in all other tables, the next step.

  async function bootstrap() {
  await powersync.init()

  const connector = new PowersyncConnector(auth)
  connector.registerListener({
    initialized: async (user) => {
      if (user == null)
        await createUserUseCase() // here is where you create your "default" user
    },

    // user is signed in when this is called
    sessionStarted: async (user) => {
      // STUB for now
      const isSyncMode = getSyncEnabled(powersync.database.name)
      console.warn('[TODO]: use sync mode')

      await powersync.connect(connector)
    },
  })

  await connector.init()
}

As for the PowersyncConnector, you'll also need to add the initialized listener.

type ConnectorListener = {
  // note that here the user can be `null`
  initialized: (user: User | null) => Promise<void>
  sessionStarted: (user: User) => Promise<void>
}

export class PowersyncConnector
  extends BaseObserver<ConnectorListener>
  implements PowerSyncBackendConnector {
  readonly sbClient: SupabaseClient

  ready: boolean

  auth: Auth

  constructor(auth: Auth) {
    super()

    this.ready = false

    this.auth = auth

    this.sbClient = createClient(
      config.supabaseUrl,
      config.supabaseAnonKey,
      {
        accessToken: async () =>
          (await this.auth.currentUser?.getIdToken(false)) ?? null,
      },
    )

    auth.onAuthStateChanged(user => this.updateUser(user))
  }

  async init() {
    if (this.ready)
      return

    await this.auth.authStateReady()
    this.updateUser(this.auth.currentUser)

    this.ready = true
    this.iterateListeners(
      async cb => cb.initialized?.(this.auth.currentUser),
    )
  }

  updateUser(user: User | null) {
    if (user)
      this.iterateListeners(async cb => cb.sessionStarted?.(user))
  }

  // rest of the connector...
}

</section>

Sidebar: User ID References in Tables

With Supabase and row-level security, I have a policy enabling changes to a row only if the ID of the user making the request matches the uid row on the table. <label for="supabase-policy" class="margin-toggle">⊕</label> <input type="checkbox" id="supabase-policy" class="margin-toggle"/> <span class="marginnote"> ⚠ The way I'm getting the uid here is because of Firebase Auth. Your case may be different or similar. Who even understands JWTs? </span>

ALTER POLICY "Enable all for owner"
ON "public"."<table_name>"
TO PUBLIC
USING ((SELECT (auth.jwt() ->> 'sub'::text)) = uid);

It wasn't directly used in the app so I hadn't had it in my schema till now.

For the schema switch on auth it'll be especially important to have this row defined so that the logged out data can be assigned to the user on transfer.

import type { BaseColumnType } from '@powersync/web'

import { column } from '@powersync/web'

const listsDef = {
  columns: {
    uid: column.text as BaseColumnType<string>,
    /* other table columns */
  },
  options: (viewName: string, localOnly = false) => ({
    viewName,
    localOnly,
  }),
}

const todosDef = {
  columns: {
    uid: column.text as BaseColumnType<string>,
    /* other table columns */
  },
  options: (viewName: string, localOnly = false) => ({
    viewName,
    localOnly,
    /* other table options */
  }),
}

</section>

Local to Sync Data Transfer

Now, after all this prep, lets write the meat and bones of this operation.

After a user signs in or registers, we want to take all the data from the local tables and insert it into the synced tables.

Then we update the syncEnabled state to make sure we're using these snazzy new tables.

Finally we clear out the local tables (unless you want that data to still be present when they sign out again).

When a user signs out, we clear everything and disable sync.

So here's the basic approach if you have a just few tables.

// powersync/switchSchema.ts

import type { PowerSyncDatabase } from '@powersync/web'

import { makeSchema } from './schema'
import { setSyncEnabled } from './syncMode'

// moved these 2 here for convenience
export function syncedName(table: string, synced: boolean) {
  return synced ? table : `inactive_synced_${table}`
}

export function localName(table: string, synced: boolean) {
  return synced ? `inactive_local_${table}` : table
}

export async function switchToSyncedSchema(db: PowerSyncDatabase, userId: string) {
  await db.updateSchema(makeSchema(true))
  setSyncEnabled(db.database.name, true)

  await db.writeTransaction(async (trx) => {
    const todosColumns = Object.keys(todosDef.columns).toString()
    await trx.execute(`
      INSERT INTO todos(id, ${todosColumns})
      SELECT id, ${todosColumns}
      FROM ${localName('todos', true)}
    `)

    // I filter out `uid` to manually add it in the position I want for the query
    const listsColumns = Object.keys(listsDef.columns).filter(c => c !== 'uid').toString()
    await trx.execute(`
      INSERT INTO lists(id, ${listsColumns}, uid)
      SELECT id, ${listsColumns}, ?
      FROM ${localName('lists', true)}
    `, [userId])


    // clear out all local tables
    trx.execute(`DELETE FROM ${localName('todos', true)}`)
    trx.execute(`DELETE FROM ${localName('lists', true)}`)
  })
}

export async function switchToLocalSchema(db: PowerSyncDatabase) {
  await db.updateSchema(makeSchema(false))
  setSyncEnabled(db.database.name, false)

  await db.writeTransaction(async (trx) => {
    await Promise.all(['todos', 'lists'].map(
      async name => trx.execute(`DELETE FROM ${syncedName(name, true)}`),
    ))
  })
}

Not all tables are created equal

In my case, I didn't have just a few tables and some were more equal than others.

At 10 tables (double that for the local_* ones), I needed the loop.

I also had those pesky "true local only" tables that I don't want to sync but do want to clear out.

Finally my user tables would conflict against my Supabase constraints.

These "lesser" tables had to go, but in slightly different ways, so I make an array of tables to exclude, and turn everything into a loop.

First, the undesirables:

/** Tables to exclude from local -> online sync. */
export const SYNC_EXCLUDED_TABLES = [
  /** `draft_*` tables are local only and can be wiped. */
  'draft_',

  /** `inactive_*` tables are temporary copies to ignore. */
  'inactive_',

  /** The local user is discarded to prevent sync conflicts. */
  'users',
]

/** Tables to exclude from purge during auth state switch. */
export const DELETE_EXCLUDED_TABLES = [
  /** `inactive_*` tables are temporary copies to ignore. */
  'inactive_',

  /** `draft_*` tables are local only and can be wiped. */
  'draft_',

  // We DO want to clear the local user table
  // 'users',
]

Now all loopified: <label for="metaphor" class="margin-toggle">⊕</label> <input type="checkbox" id="metaphor" class="margin-toggle"/> <span class="marginnote"> There's also that uid column on every table that I want to treat extra special. </span>

// powersync/switchSchema.ts

import type { PowerSyncDatabase } from '@powersync/web'

import { DELETE_EXCLUDED_TABLES, SYNC_EXCLUDED_TABLES } from './constants'
import { makeSchema } from './schema'
import { setSyncEnabled } from './syncMode'

export function syncedName(table: string, synced: boolean) {
  return synced ? table : `inactive_synced_${table}`
}

export function localName(table: string, synced: boolean) {
  return synced ? `inactive_local_${table}` : table
}

export async function switchToSyncedSchema(db: PowerSyncDatabase, userId: string) {
  await db.updateSchema(makeSchema(true))
  setSyncEnabled(db.database.name, true)

  await db.writeTransaction(async (trx) => {
    const tableNames = db.schema.tables
      .filter(t => SYNC_EXCLUDED_TABLES.every(ex => !t.viewName.startsWith(ex)))
      .map(t => ({
        sync: t.viewName,
        local: localName(t.viewName, true),
        columns: Object.keys(t.columnMap).filter(c => c !== 'uid'),
      }))

    // manually add `id`, it's there by default but not in the table definitions
    // adding `uid` at the end to make sure of the order
    await Promise.all(tableNames.map(async t => trx.execute(`
      INSERT INTO ${t.sync}(id, ${t.columns.toString()}, uid)
      SELECT id, ${t.columns.toString()}, ?
      FROM ${t.local}
    `, [userId])))

    // clear out all local tables
    const localOnlyTables = db.schema.tables
      .filter(t => DELETE_EXCLUDED_TABLES.every(ex => !t.viewName.startsWith(ex)))
      .map(t => localName(t.viewName, true))
    await Promise.all(localOnlyTables.map(async name => trx.execute(`DELETE FROM ${name}`)))
  })
}

export async function switchToLocalSchema(db: PowerSyncDatabase) {
  await db.updateSchema(makeSchema(false))
  setSyncEnabled(db.database.name, false)

  await db.writeTransaction(async (trx) => {
    const syncTables = db.schema.tables
      .filter(t => DELETE_EXCLUDED_TABLES.every(ex => !t.viewName.startsWith(ex)))
      .map(t => syncedName(t.viewName, true))
    await Promise.all(syncTables.map(async name => trx.execute(`DELETE FROM ${name}`)))
  })
}

Presto! We're ready to wire all this up. </section>

Switching Sync Mode on Auth

Now lets do the skin and hair of this operation! <label for="metaphor-extended" class="margin-toggle">⊕</label> <input type="checkbox" id="metaphor-extended" class="margin-toggle"/> <span class="marginnote"> How's my metaphor extension? <br> Call 1-800-888-8888 </span>

So where are we at now?

Tables are ready
Schema is parametric
Data switching is set up
We know whether to sync or not

Now we orchestrate all these elements together.

0. In PowerSync init

Now that things will be wired up, we can forego the hardcoded value.

const syncEnabled = getSyncEnabled(DB_NAME)

export const powersync = new PowerSyncDatabase({
  schema: makeSchema(syncEnabled),
  database: new WASQLiteOpenFactory({ dbFilename: DB_NAME }),
})

1. On sign in or register

Here we have a newly authenticated user while still being in sync mode off.

That means it's time to switch to sync mode and transfer the data.

// main.ts

sessionStarted: async (user) => {
  const isSyncMode = getSyncEnabled(powersync.database.name)
  if (isSyncMode === false)
    await switchToSyncedSchema(powersync, user.uid)

  await powersync.connect(connector)
},

2. On sign out

Wherever you've got your sign out logic, you'll want to then switch back to local tables and turn sync mode off.

Here's what that looks like for me.

import { auth } from '@/features/auth'
import { powersync, switchToLocalSchema } from '@/libraries/powersync'

export async function signOutUserUseCase() {
  if (auth.currentUser == null)
    throw new Error('Unable to logout.')

  await powersync.disconnectAndClear()
  await switchToLocalSchema(powersync)
  await auth.signOut()

  // this erases the sync mode key but it gets initialized to `false` so all good
  localStorage.clear()

  window.location.reload()
}

Sidebar: In the router

Now here is a Vue-ism so your version may vary.

I found that waiting for the first database sync prevented a blank loading page which isn't very local-first or it loaded partial data until a refresh.

router.beforeEach(async (to) => {
  if (auth.currentUser != null)
    await database.waitForFirstSync()

  // rest of your router guard logic...
})

And that's it, you're all done! <label for="thats-not-all" class="margin-toggle">⊕</label> <input type="checkbox" id="thats-not-all" class="margin-toggle"/> <span class="marginnote">Narrator: That was not it, and I was not done...</span>

We set up all the dominoes and got to watch them fall (which always happens much faster than the setup). </section>

Sidebar: Insert Order of Operations

So uhm yeah, this is a sidebar, so maybe you're not gonna run into this at all. But I ran into it, at full speed...

My riches of tables have multiple foreign key references. They depend on each other in a specific directed acyclic order.

What ends up happening after the switch is that the transaction operation happens in an order you can't quite control (as far as I know). Leading to a bunch of:

ERROR: insert or update on table "child_table" violates foreign key constraint "fk_constraint_name"

DETAIL: Key (parent_id)=(100) is not present in table "parent_table". <footer>My console, multiple times.</footer>

Our underlying local(-first) SQLite table doesn't have the foreign key constraint turned on by default. We can insert whatever we want in the order we want, then if all the data references are good when the transaction ends, you're good. Postgres is not so kind.

The fix was straightforward but exhausting.

Have a list of your working table insertion order: <label for="insertion-order" class="margin-toggle">⊕</label> <input type="checkbox" id="insertion-order" class="margin-toggle"/> <span class="marginnote"> If A references B which references C, you'll want to go [C, B, A] </span>

/** Foreign key reference safe table order in which to insert data. */
export const INSERT_ORDER: Tables[] = [
  /* list them here in order of insertion */
]

Then make sure to sort the operations in the PowersyncConnector: <label for="a-better-place" class="margin-toggle">⊕</label> <input type="checkbox" id="a-better-place" class="margin-toggle"/> <span class="marginnote"> I believe there's a better way and place to do this but I have not found it. </span>

export class PowersyncConnector
  extends BaseObserver<ConnectorListener>
  implements PowerSyncBackendConnector {

  async uploadData(database: AbstractPowerSyncDatabase): Promise<void> {
    const transaction = await database.getNextCrudTransaction()

    if (!transaction)
      return

    let lastOp: CrudEntry | null = null
    try {
      // due to foreign key references inserts need to happen in a particular order
      // this is mostly relevant for transfering logged out data to logged in accounts
      // other places already do it in the right order
      const sortedCrud = transaction.crud
        .toSorted((a, b) => INSERT_ORDER.indexOf(a.table) - INSERT_ORDER.indexOf(b.table))

      for (const op of sortedCrud) {
        // and so on and so forth...
      }
    }
  }
}

That should be it. <label for="narrator-crickets" class="margin-toggle">⊕</label> <input type="checkbox" id="narrator-crickets" class="margin-toggle"/> <span class="marginnote"> Narrator (begrudgingly): That was it. </span>

</section>

Conclusion

First off, big thanks for making it to the end. This is the longest post so far but the struggles I faced implementing this drove me to write. If you're another local-first afficionado and decide to undertake this feature as well I hope this helps you out.

With this, our app now works without requiring users to create an account unless they want to. Should they choose to do so, they will find their autonomy respected and their data preserved*. <label for="asterisk" class="margin-toggle">⊕</label> <input type="checkbox" id="asterisk" class="margin-toggle"/> <span class="marginnote"> *If you've got a PWA, I can't make any promises for how long a user's device will keep browser storage before choosing to clear it out. I don't know if the universe where wasm sqlite stores information is protected. But with an account and data synced, it should last until you accidentally wipe it yourself. </span>

Make sure to test the hell out of this. You're dealing with auth and precious user data. </section>

Empty State Onboarding

Maximilien Monteil — Mon, 02 Feb 2026 00:00:00 GMT

Empty State Onboarding

I've been working on my app Mylo for quite some time now. It's a workout app aimed at athletes, or anyone that does "standard" training like in the gym and then does some sport specific training.

There's a lot of workout apps out there but I never found one that had the flexibility you'd need for some of the crazy sport-specific training I've seen. <label for="crazy-sports-tangent" class="margin-toggle">⊕</label> <input type="checkbox" id="crazy-sports-tangent" class="margin-toggle"/> <span class="marginnote"> Think about wild sports like Slap Fighting. It's got pro leagues and all. They're training for this, but how? I don't know of an app that would support this. </span>

Anyways, Mylo has been almost done for quite a long time but lately I've really been blasting through my launch checklist and now I only have the dreaded 10% left. </section>

10% left AKA you forgot about onboarding (1%)

One part of the 10% is onboarding.

Getting strangers familiar with something that's become second nature to me now after all my time with it.

Now onboarding, like most things, has a massive rabbit hole behind it with full on psychology studies. For me and my goals here, onboarding is the act of educating and informing a new person how something works.

I've seen 4 main ways to onboard a user onto an app. They all have their goals and likely fit better in some experiences better than others, but I had my gripes with most of them.

1. Welcome Slides

That's when the app opens up for the first time with a sort of fullscreen slideshow of the features and benefits of the app that you can click or swipe through.

I find this is often the same slides you see in the app store showcase. It usually says something you already know, you installed the app, you're already convinced.

I tend to swipe through this as fast as possible or press the skip button.

2. Guided Clicking Tour

Here the app takes you along this on-rails experience, highlighting different parts of the app to click on. Like a video game tutorial.

This can work if it isn't too long or if the app is in fact very complicated, but I think it takes away too much agency from the user.

I've just landed in a new place, I'd like to explore a bit at my own pace.

The tour can also lead to information overload, in a few minutes you get sheparded from place to place, semi-thoughtlessly following prompts. Once done it can be tougher to do the same steps again alone, kinda like the feeling of tutorial hell.

3. Intro Setup Form

With the intro form, the app opens up with some simple questions to help setup the app for your use case.

For a workout app for example, this would be the one that asks your experience level, gender, height, blood type, astrological sign, and then does something with it.

Most egregiously, I've seen this use the sunken cost principle to offer some paid thing once your a few steps too far. Some even have little encouragement messages in between to keep you going.

This once again takes away agency, it can be useful though if you're filling out info that will rarely need to change and it ends with some actionable result.

4. Self Explanatory Interface

Maybe a nice way of saying there's no onboarding. But if the product is extremely well executed, this may be the holy grail.

I liken it to physical products like a door handle. It doesn't take too much effort to figure it out without a guide. <label for="handle-tangent" class="margin-toggle">⊕</label> <input type="checkbox" id="handle-tangent" class="margin-toggle"/> <span class="marginnote"> Even the "simplest" and "most-obvious" item can still confuse someone or be used in unintended ways. Like door handles serving as in-a-pinch dentists for loose teeth. </span>

This is the best version for sure, but near impossible to achieve. </section>

Enter: Empty State Onboarding

The above methods need careful execution and a good app likely needs some combination.

In my hubris though, I wanted none of that.

I wanted onboarding that doesn't get in your way, onboarding that is present only when you'd need it. It should be dismissable yet still accessible afterwards.

To make it cool I gave it a name: Empty State Onboarding <label for="name-tangent" class="margin-toggle">⊕</label> <input type="checkbox" id="name-tangent" class="margin-toggle"/> <span class="marginnote"> This probably already exists with a different name. <a href="https://xkcd.com/927/">Now we have 15 standards.</a> </span>

In a nutshell, this onboarding works kind of like placeholders.

In a place or situation where some action is expected of the user, relevant help information is presented about exactly the next step to take, right where you need to take it.

In a multi-step flow, each part would entice the next step, which then reveals the next bit of helpful information.

Dynamic Empty State Onboarding ~the Reckoning~

One step further is persistent Empty State Onboarding on screens that would get filled up from multiple steps that need to be accomplished elsewhere.

In the case of Mylo, the main page is your training schedule, which starts off empty when you don't have any workouts.

Onboarding there asks you to create a workout as step 1 with a button to directly go do that.

Step 2 below is visible but grayed out.

Once step 1 is complete, if you come back here, step 2 is now clearer and shows a helpful list of the workout(s) you just made and you can directly add them to your schedule from there.

For a new user, this shortcuts the action until you get more familiar with the app. Later on, once the new environment is more familiar, you'll be more comfortable checking out more things. </section>

Education and Dismissal

The last step is education.

These onboarding bits of info can be dismissed, but they re-appear the next time.

Dismiss it once more and the next time you see it, you can permanently make it go away.

That means you see it 3 times at least helping you remember the information (or you can dismiss it right away).

But what if you dismissed it in a hurry, or some time later you have questions?

For this, I felt an important part of good onboarding is making this information always available later. So in the settings page you can see a "Help & Guides" section where that same onboarding information is present. </section>

Conclusion

So this was my approach to onboarding. <label for="images-tangent" class="margin-toggle">⊕</label> <input type="checkbox" id="images-tangent" class="margin-toggle"/> <span class="marginnote"> I really need to add some images to my blog, would have made this post much easier to understand... Thank you for getting this far dear reader! </span>

I'll have to see how people actually respond to it, it might fail and I fallback to a more classic approach.

But! It might work wonders and help new users find their way around a new app without feeling a loss of control or curiosity.

Empty state onboarding also better matches my values for Mylo. It's there to help you and support you but without getting in your way or forcing an approach on you. </section>

SVG Favicons?!

Maximilien Monteil — Sun, 18 Jan 2026 00:00:00 GMT

SVG Favicons?!

In the process of making this site I naturally needed a proper favicon.

So I first went to delete the default one from the Astro generated site and noticed that it was an SVG file. Up till this point I had only ever encountered good old .ico files (which I only saw elsewhere with windows desktop icons.) <label for="favicon-tangent" class="margin-toggle">⊕</label> <input type="checkbox" id="favicon-tangent" class="margin-toggle"/> <span class="marginnote"> As a tangent, favicons are one of these things I know about but rarely ever touch, and once you dig a bit, turns out <a href="http://johnsalvatier.org/blog/2017/reality-has-a-surprising-amount-of-detail">favicons have a surprising amount of detail</a> with different sizes, browser support, situational formats, and more. </span> </section>

Astro's default favicon

I open up the file and find yet another surprise, you can insert stylesheets directly into SVGs!

In hindsight that seems obvious because SVGs already look so "HTML-like". In the case of the default Astro favicon (and now mine hehe) you can add some styling to dynamically change the favicon based on color scheme.

<svg
  xmlns="http://www.w3.org/2000/svg"
  fill="none"
  viewBox="0 0 128 128"
>
  <rect width="128" height="128" rx="16"/>
  <path d="..."/>
  <path fill-opacity=".7" d="..."/>
  <style>
    rect { fill: #fffff8; }
    path { fill: #111; }
    @media (prefers-color-scheme: dark) {
      rect { fill: #151515; }
      path { fill: #ddd; }
    }
  </style>
</svg>

I didn't look much deeper but I wonder if you get full CSS access in there, you could animate it to start, but with how capable CSS has become, I'm sure there are some crazy things that could be done.

Including your SVG favicon

To then include it, just make sure to have the correct type attribute in the link tag:

<link
  rel="icon"
  type="image/svg+xml"
  href="/favicon.svg"
/>

</section>

Bonus: Fonts can also be SVGs

Is there anything they can't do? <label for="svg-power-tangent" class="margin-toggle">⊕</label> <input type="checkbox" id="svg-power-tangent" class="margin-toggle"/> <span class="marginnote"> I read somewhere that SVGs can in fact do pretty much anything. You can include JS, fetch data and then animate some data visualization directly in there. You can propably run DOOM in an SVG. </span>

Now if SVG is a good format for fonts, I can't say. There's likely the usual benefits of SVGs being vectors and thus looking sharp at any size, but maybe the file size is worse? Latest recommended font format (for web at least) is WOFF 2: The Reckoning.

Regardless, after finding out you can style SVGs, and being super happy with Tufte CSS, I wanted to mimick that.

Classy favicon with "mm", so to Figma I go.

Roadblock 1

I have the font I want (ET Book) but can't use it in Figma unless I install the app or use their font installer which I don't want to do.

Luckily, I can open the SVG font in my editor<label for="sn-nvim" class="margin-toggle sidenote-number"></label> <input type="checkbox" id="sn-nvim" class="margin-toggle"/><span class="sidenote">I use Neovim btw</span> and find what I'm looking for at glyph unicode="m", perfect.

Roadblock 2

I've got the glyph line but I can't paste that into Figma, so I try to jam it into an SVG:

<!-- before -->
<glyph
  unicode="m"
  horiz-adv-x="1662"
  d="M35 8q-3 8"
/>

<!-- after -->
<svg xmlns="http://www.w3.org/2000/svg">
  <path fill="#000" d="M35 8q-3 8" />
</svg>

Is this valid? Probably not.

But I could now paste it into Figma, though it was upside down and flipped vertically, likely from the missing viewBox, but that's an easy fix.

So I make my Favicon, pass it through the eternally amazing SVGOMG, slap it onto my site and badabing badaboom SSStylish!<label for="theme-toggle-tangent" class="margin-toggle">⊕</label> <input type="checkbox" id="theme-toggle-tangent" class="margin-toggle"/> <span class="marginnote"> I should add a light/dark theme toggle... <br> Edit: I added one! And it wiggles!! </span> </section>