DEV Community: Fredy Sandoval

Lessons from Astro Starlight: Designing a Maintainable i18next Architecture

Fredy Sandoval — Tue, 25 Aug 2026 14:25:04 +0000

Astro Starlight is a useful reference implementation for internationalization because it does not treat i18next as the entire i18n system.

Instead, Starlight uses several layers:

the application/framework determines which locale is active;
translation files are treated as validated application data;
multiple translation sources are merged according to an explicit precedence;
i18next provides the actual translation engine;
consumers receive a small, locale-bound t() API;
TypeScript and schemas make invalid translation usage harder;
plugins and third-party UI systems participate in the same translation pipeline.

This separation is the main lesson worth carrying into Astro, React, Next.js, server-rendered applications, component libraries, and other projects.

Starlight currently depends on i18next directly and creates its own i18next instance rather than using the package-global singleton.

1. Separate locale resolution from translation lookup

A common i18next implementation starts by asking i18next to detect the user's language.

Starlight takes a different approach.

Astro/Starlight first resolves the locale from the application's routing configuration. That locale is then passed into the translation system. Middleware creates a translation function for context.currentLocale and exposes it to the rest of the request as Astro.locals.t.

Conceptually:

request
   ↓
router / application locale resolution
   ↓
locale = "fr"
   ↓
translation service
   ↓
t = getTranslator("fr")
   ↓
component
   ↓
t("navigation.home")

This is preferable to making i18next simultaneously responsible for:

URL routing
cookie handling
browser detection
locale selection
translation loading
translation lookup

Those are separate responsibilities.

General lesson

Design an application-level locale resolver first.

For example:

type Locale = 'en' | 'fr' | 'es';

function resolveLocale(request: Request): Locale {
  // Depending on your application:
  // 1. URL
  // 2. authenticated user preference
  // 3. cookie
  // 4. Accept-Language
  // 5. default locale
}

Then make translation lookup explicit:

const t = getTranslator(locale);

For a React SPA, browser-language detection may still be appropriate. The important part is that locale resolution should have a clearly defined owner rather than emerging accidentally from several libraries.

For SSR applications, this separation is particularly useful because the server already knows which locale is rendering the request.

2. Treat translation dictionaries as application data

Starlight does not simply import arbitrary JSON and hope that keys are correct.

Its i18n collection has a Zod schema. The schema describes recognized translation keys and even attaches descriptions explaining what each string represents.

Examples include concepts such as:

search.label
themeSelect.dark
languageSelect.accessibleLabel
tableOfContents.onThisPage
page.previousLink
aside.warning
heading.anchorLabel

The important idea is:

translations are data with a contract

rather than:

translations are arbitrary Record<string, string>

Why this matters

A schema can detect:

invalid value types;
misspelled keys;
unsupported structures;
malformed generated catalogs;
accidental translation metadata;
plugin-specific extensions.

It can also become a source for:

editor autocomplete;
translation documentation;
automated catalog validation;
translation-management tooling;
generated TypeScript declarations.

Recommended pattern

Maintain a canonical schema beside your i18n infrastructure:

import { z } from 'zod';

export const uiMessagesSchema = z.object({
  'navigation.home': z.string(),
  'navigation.settings': z.string(),

  'search.label': z.string(),
  'search.results': z.string(),

  'account.signOut': z.string(),
});

A more mature system can store translator context:

const messages = {
  'navigation.home': {
    description: 'Primary navigation link to the application home page',
  },

  'account.signOut': {
    description: 'Button used to terminate the current authenticated session',
  },
};

Translator context is not cosmetic. A translator seeing only:

"open": "Open"

does not know whether "open" is a verb, adjective, menu state, button, or accessibility label.

3. Use different validation strictness for canonical and override catalogs

Starlight makes an interesting distinction.

Its bundled Starlight strings are validated against a stricter schema, while the schema exposed to application users is partial and extensible. This lets a project provide only the translations it wants to override rather than having to reproduce the complete Starlight catalog.

This suggests a strong general pattern.

Canonical/default locale

Require everything:

const defaultCatalogSchema = uiMessagesSchema.required();

A missing English source string should fail CI or the build.

Secondary locales

Depending on your translation workflow, either require completeness:

const localeCatalogSchema = uiMessagesSchema.required();

or deliberately allow incremental translation:

const localeCatalogSchema = uiMessagesSchema.partial();

with runtime fallback to the default locale.

The decision should be explicit.

Do not accidentally allow partial translation simply because JSON files are unchecked.

4. Establish an explicit translation precedence

Starlight combines three categories of translations:

Starlight built-ins
       ↓
plugin translations
       ↓
project/user translations

The resource builder processes them in that order, so later sources can override earlier ones. Undefined or missing entries do not erase an earlier translation.

This produces a clear policy:

framework defaults < extension defaults < application overrides

That is a highly reusable pattern.

For a component platform, the equivalent might be:

design-system defaults
        ↓
feature-package translations
        ↓
application translations
        ↓
customer/tenant overrides

Implement the policy explicitly:

function buildCatalog(
  core: Messages,
  extensions: Messages,
  app: Messages,
): Messages {
  return {
    ...core,
    ...extensions,
    ...app,
  };
}

For complex systems, prefer a merge function that can distinguish:

missing
undefined
empty string
null
intentional deletion

Starlight itself ignores falsy translation values while merging. That behavior is worth understanding rather than copying blindly.

5. Give extensions a translation registration API

Starlight plugins do not need access to the internals of the i18next resource store.

Instead, plugins participate in an i18n:setup phase and call:

injectTranslations({
  en: {
    'myPlugin.doThing': 'Do the thing',
  },
  fr: {
    'myPlugin.doThing': 'Faire le truc',
  },
});

Those strings become available through the same translation API as Starlight's built-in strings.

This is a useful architecture for:

plugins;
feature modules;
packages in a monorepo;
design systems;
microfrontends;
third-party integrations.

Instead of allowing every feature to initialize i18next independently, define an extension contract.

For example:

interface TranslationExtension {
  namespace: string;
  resources: Record<string, Record<string, string>>;
}

registerTranslations({
  namespace: 'billing',
  resources: {
    en: {
      'billing.invoice.download': 'Download invoice',
    },
    fr: {
      'billing.invoice.download': 'Télécharger la facture',
    },
  },
});

Starlight's plugin examples use keys prefixed with the plugin name, such as myPlugin.doThing, which is a practical convention for avoiding collisions.

6. Hide the raw i18next instance behind an application API

Starlight creates a dedicated i18next instance:

const i18n = i18next.createInstance();

await i18n.init({
  resources,
  fallbackLng,
});

It then returns locale-bound translators using getFixedT().

i18next itself documents createInstance() for separate i18next instances and getFixedT() for generating a translation function bound to a language or namespace.

This means most Starlight components do not care about initialization.

They receive something conceptually equivalent to:

const t = getTranslator('fr');

t('search.label');

General lesson

Your application code should depend primarily on:

t(...)

not:

i18next.changeLanguage(...)
i18next.addResourceBundle(...)
i18next.init(...)
i18next.services.resourceStore...

Keep those operations in the infrastructure layer.

A useful API might be:

export interface Translator {
  (key: TranslationKey, options?: TranslationOptions): string;

  exists(key: TranslationKey): boolean;
  dir(locale?: string): 'ltr' | 'rtl';
  all(): Readonly<Record<string, string>>;
}

Starlight adds exactly this kind of convenience around i18next: its translator exposes t(), t.exists(), t.dir(), and t.all().

7. Bind translators to the request or rendering context

Starlight does not continually mutate one global current language.

Instead, it uses getFixedT(locale, namespace) to obtain a translator for a particular locale. Middleware attaches that translator to the current request.

This is especially relevant for SSR.

A global mutable language can create problems when a server handles concurrent requests:

request A → French
request B → Japanese

If both mutate a shared singleton's active language, isolation becomes important.

A safer server-side model is:

const t = getTranslator(requestLocale);

or an i18next instance scoped appropriately for the request/application architecture.

For React SSR, react-i18next also documents passing an i18next instance through I18nextProvider, including request-specific instances for SSR scenarios.

8. Make fallback behavior part of the product policy

Starlight explicitly sets its default locale as the fallbackLng.

Its documentation also treats fallback as a product feature: untranslated documentation pages can fall back to content in the default language instead of simply disappearing.

The translation equivalent is:

requested locale
       ↓
less-specific locale if applicable
       ↓
application default locale

i18next has built-in language-variant fallback behavior. For example, a regional locale can fall back to its broader language before the configured fallback language.

A general application should therefore document fallback rules explicitly:

export const DEFAULT_LOCALE = 'en';

export const supportedLocales = [
  'en',
  'en-GB',
  'fr',
  'fr-CA',
  'es',
] as const;

Do not let locale fallback be whatever i18next happens to do by default. i18next's default fallback is dev; its documentation recommends explicitly selecting a real fallback language for production applications.

9. Use proper locale identifiers

Starlight uses BCP-47 language tags and relies on platform internationalization APIs such as Intl.Locale and Intl.DisplayNames to derive information about locales. It also exposes language direction through the translation API.

Prefer:

en
en-US
en-GB
pt-BR
zh-CN
zh-TW

rather than application-specific formats such as:

english
en_US
brazilian
zh_chinese

BCP-47-compatible identifiers cooperate better with:

Intl;
browsers;
HTTP language headers;
i18next;
translation vendors;
date/number formatting APIs.

One Starlight implementation detail should not necessarily be copied: its helper for locating a bundled base-language translation uses a relatively simple region-stripping function. A general-purpose application with scripts and complex language variants should rely on proper locale negotiation rather than inventing BCP-47 parsing.

10. Make RTL direction part of the i18n service

Internationalization is not only translated strings.

Starlight exposes:

t.dir()

and uses that result to produce ltr or rtl. Its locale configuration also includes writing direction.

A general application should make direction available globally:

function AppShell({ locale }: { locale: string }) {
  const dir = i18n.dir(locale);

  return (
    <html lang={locale} dir={dir}>
      ...
    </html>
  );
}

CSS should then favor logical properties:

margin-inline-start
padding-inline-end
border-inline-start
inset-inline-end

instead of building separate RTL styles around left and right.

11. Keep translation keys stable and semantic

Starlight's catalogs use keys such as:

search.label
themeSelect.dark
tableOfContents.onThisPage
page.previousLink
heading.anchorLabel

rather than using the English text itself as the identifier.

This allows copy to change without changing the application's API.

Prefer:

t('checkout.payment.submit')

over:

t('Pay now')

A practical naming structure is:

domain.component.meaning

Examples:

auth.login.submit
auth.login.invalidPassword

billing.invoice.download
billing.invoice.status.overdue

navigation.account.settings
navigation.account.signOut

For packages or plugins, prefix keys with the package identity:

analytics.export.csv
editor.toolbar.bold
myPlugin.settings.title

12. Use interpolation for dynamic values, not sentence construction

Starlight exposes normal i18next interpolation:

{
  "heading.anchorLabel": "Section titled “{{title}}”"
}

and custom application strings can similarly use:

{
  "link.astro.custom": "Astro documentation for {{feature}}"
}

The value is supplied through the t() options object.

Use interpolation when a value is genuinely dynamic:

t('welcome.user', { name });
t('files.count', { count });

Avoid constructing sentences from fragments:

t('youHave') + count + t('messages');

i18next's own best-practices documentation warns that excessive interpolation and sentence fragmentation create localization problems because languages do not share the same grammar or word ordering.

Pluralization should similarly remain inside the translation system rather than application conditionals. i18next's plural rules use Intl.PluralRules and the count option.

13. Integrate third-party UI into the same translation pipeline

One particularly useful Starlight pattern appears in search.

Pagefind is a separate library with its own UI translation API. Rather than creating an entirely separate locale system, Starlight extracts pagefind.* entries from its central translation dictionary, removes the prefix, and passes them to Pagefind.

Conceptually:

const searchTranslations = Object.fromEntries(
  Object.entries(t.all())
    .filter(([key]) => key.startsWith('searchProvider.'))
    .map(([key, value]) => [
      key.replace('searchProvider.', ''),
      value,
    ]),
);

thirdPartySearch.init({
  translations: searchTranslations,
});

This is an excellent general rule:

The application owns localization. Third-party widgets should consume translations from the application's localization pipeline whenever possible.

That prevents:

main application locale = French
date picker locale = English
search UI locale = browser language
editor locale = previously saved setting

from becoming four independent systems.

14. Make translation keys part of the TypeScript API

Starlight augments i18next's CustomTypeOptions so the starlight namespace knows its translation keys. User schema keys and plugin keys are also incorporated into the translation type.

Plugin translations are particularly interesting: Starlight collects injected keys and generates a TypeScript declaration file in the consuming project so those keys become part of the typed translation API.

The goal is:

t('navigation.home');       // valid
t('navigaton.home');        // TypeScript error

instead of discovering the typo in production.

i18next officially supports TypeScript resource typing through CustomTypeOptions.

For a normal application, a simpler approach is often sufficient:

import en from './locales/en/common.json';

declare module 'i18next' {
  interface CustomTypeOptions {
    defaultNS: 'common';

    resources: {
      common: typeof en;
    };
  }
}

For a large modular project, generate those declarations from your translation registry or source locale.

15. File structure: what to copy and what to adapt

Starlight itself keeps bundled UI translations as one file per locale and supports project translations from src/content/i18n/*.json, .yaml, or .yml.

A small application can use:

src/
  i18n/
    index.ts
    config.ts
    schema.ts
    locales/
      en.json
      fr.json
      es.json

For a larger React application, namespaces usually scale better:

src/
  i18n/
    config.ts
    createI18n.ts
    resolveLocale.ts
    types.ts
    schemas/
      common.ts
      billing.ts
      editor.ts

    locales/
      en/
        common.json
        billing.json
        editor.json

      fr/
        common.json
        billing.json
        editor.json

Starlight uses one starlight i18next namespace because its UI catalog is relatively cohesive. i18next explicitly recommends multiple namespaces when catalogs become large, belong to different semantic areas, or should be lazy-loaded separately.

Therefore, the lesson is not "always use one namespace."

The lesson is:

choose namespace boundaries deliberately

16. A generalized architecture

A reusable i18next architecture based on Starlight's strongest ideas looks like this:

                 ┌─────────────────────────┐
                 │    Locale Resolver      │
                 │ URL / user / cookie /   │
                 │ Accept-Language         │
                 └────────────┬────────────┘
                              │
                              ▼
                 ┌─────────────────────────┐
                 │      Locale Config      │
                 │ supported / default /   │
                 │ BCP-47 / direction      │
                 └────────────┬────────────┘
                              │
                              ▼
    ┌─────────────┐   ┌───────────────────┐   ┌─────────────┐
    │ Core        │   │ Feature / plugin  │   │ Application │
    │ catalogs    │   │ catalogs          │   │ overrides   │
    └──────┬──────┘   └─────────┬─────────┘   └──────┬──────┘
           │                    │                    │
           └────────────────────┼────────────────────┘
                                ▼
                    ┌─────────────────────┐
                    │ Schema validation   │
                    │ + type generation   │
                    └──────────┬──────────┘
                               ▼
                    ┌─────────────────────┐
                    │ Resource assembly   │
                    │ explicit precedence │
                    └──────────┬──────────┘
                               ▼
                    ┌─────────────────────┐
                    │ private i18next     │
                    │ instance            │
                    └──────────┬──────────┘
                               ▼
                    ┌─────────────────────┐
                    │ getTranslator(lang) │
                    └──────────┬──────────┘
                               │
                ┌──────────────┼──────────────┐
                ▼              ▼              ▼
             React UI       server code    third-party UI

This architecture remains useful even when none of the consuming code uses Astro.

17. Recommended React implementation

For React, retain the architecture but replace Astro.locals.t with React context through react-i18next.

A reasonable initialization layer is:

// i18n/createI18n.ts

import i18next from 'i18next';
import { initReactI18next } from 'react-i18next';

import { buildResources } from './resources';
import { defaultLocale } from './config';

export async function createAppI18n(locale: string) {
  const instance = i18next.createInstance();

  await instance
    .use(initReactI18next)
    .init({
      lng: locale,
      fallbackLng: defaultLocale,
      resources: buildResources(),
      defaultNS: 'common',

      interpolation: {
        escapeValue: false,
      },
    });

  return instance;
}

Then at the React boundary:

<I18nextProvider i18n={i18n}>
  <App />
</I18nextProvider>

Inside components:

function SaveButton() {
  const { t } = useTranslation('common');

  return <button>{t('actions.save')}</button>;
}

react-i18next's useTranslation() internally supplies a namespace-bound t function using i18next's getFixedT() mechanism, which is conceptually close to the API Starlight builds itself.

For SSR, create or select the appropriate instance for the request rather than assuming a browser-global mutable language. I18nextProvider is explicitly designed to support supplied instances and SSR use cases.

18. Suggested translation pipeline

A production pipeline can be defined as:

1. Developer adds or changes a source-language key.

2. Schema/type generation updates the canonical key contract.

3. CI validates the default catalog.

4. CI validates every locale:
   - valid keys
   - valid value types
   - interpolation placeholders
   - missing/extra keys according to project policy

5. Translation files are sent to translators or a localization platform.

6. Returned catalogs are validated again.

7. Build assembles:
   core
   + packages/plugins
   + application overrides.

8. i18next receives normalized resources.

9. Server/router determines the active locale.

10. Components receive a locale-bound translation API.

11. Third-party UI gets translations from that same API.

12. Automated tests verify fallback and representative locales.

The main architectural principle is that i18next should sit inside this pipeline rather than be the pipeline.

19. Tests worth adding

An i18n implementation should test infrastructure, not every sentence.

High-value tests include:

Default locale contains every required key.

Supported locales contain no unknown keys.

Required locales meet the chosen completeness threshold.

Interpolated placeholders match between source and translation.

Plural forms work for representative languages.

Regional locale fallback works.

Application overrides beat package defaults.

Plugin/feature translations are registered.

Missing translation falls back to the configured locale.

RTL locales return rtl.

Unknown translation keys fail TypeScript checks.

Server requests for different locales remain isolated.

Third-party widgets receive the correct current-locale dictionary.

Starlight itself tests content collections and can mock i18n collection entries during tests, reinforcing the idea that translation catalogs are part of the application's data layer.

20. What specifically should be copied from Starlight?

The most transferable Starlight decisions are:

Starlight decision	General lesson
Astro resolves the locale	Keep locale resolution outside the translation engine
`i18next.createInstance()`	Own an application-specific i18next instance
`getFixedT(locale, namespace)`	Give consumers locale-bound translators
Zod i18n schema	Validate translations as structured data
Strict bundled schema	Make canonical catalogs complete
Partial user schema	Allow controlled incremental overrides
Built-in → plugin → user merging	Define translation precedence
Plugin `injectTranslations()`	Give modules an extension API
Generated plugin key types	Make translation keys part of the TS contract
`Astro.locals.t`	Expose one simple translation API
`t.exists()`	Support capability/optional-key checks
`t.dir()`	Treat writing direction as first-class i18n data
`t.all()`	Allow integration with external UI libraries
`pagefind.*` translation forwarding	Centralize localization even for third parties
BCP-47 locale tags	Use interoperable language identifiers
Explicit fallback locale	Make missing-translation behavior predictable

21. What should not be copied literally?

Several Starlight decisions are appropriate for Starlight but should remain project-specific.

One namespace

Starlight uses one starlight namespace. Large applications may benefit from common, account, billing, editor, and other namespaces for ownership and lazy loading. i18next supports namespaces specifically for this purpose.

Eagerly assembled resources

Starlight's UI catalog is small enough to assemble into resources up front. A large client application may want lazy loading by language and namespace.

Astro content collections

The useful concept is schema-validated catalogs, not Astro's particular loader implementation. React projects can reproduce this with Zod, JSON Schema, custom build scripts, or localization-platform validation.

Astro middleware

The useful concept is request-bound translation state. Next.js middleware, Express request state, Remix loaders, React Router, or another request context can provide the equivalent.

Flat dotted keys

Starlight's dotted flat keys work well for its catalog. A project can choose flat or nested resources, but the convention should be consistent and reflected in schema/types.

22. Recommended baseline for a new project

For a new TypeScript/React project, a Starlight-inspired baseline would be:

Locale:
  use BCP-47 identifiers

Locale ownership:
  application/router resolves locale

Default:
  configure one explicit production fallback locale

Catalogs:
  JSON/YAML/TS resources organized by locale + namespace

Schema:
  validate every catalog during CI/build

Source locale:
  required and complete

Secondary locales:
  complete or deliberately partial

Keys:
  semantic, stable, domain-prefixed

Extensions:
  provide registerTranslations()/injectTranslations()

Precedence:
  platform < feature/package < application

Runtime:
  private i18next instance

React:
  I18nextProvider + useTranslation()

SSR:
  request-safe locale/instance handling

TypeScript:
  typed translation keys

RTL:
  propagate lang and dir to document root

Third parties:
  derive their dictionaries from the central catalog

Testing:
  schema, fallback, placeholders, plurals, overrides, RTL

Conclusion

The biggest lesson from Starlight is not a particular i18next option.

It is the decision to make i18next a translation engine behind an application-owned localization architecture.

A robust system has three distinct layers:

Locale architecture
    routing, detection, user preference, fallback policy

Translation architecture
    schemas, catalogs, ownership, merging, plugins, types

Rendering integration
    i18next, React/Astro adapters, t(), formatting, plurals

Keeping those layers separate makes the system easier to test, extend, migrate between frameworks, and operate at scale.

If only a few Starlight ideas are adopted, the highest-value ones are:

resolve locale outside i18next;
treat translation catalogs as validated data;
establish explicit source precedence;
expose a small locale-bound translation API;
type translation keys;
give packages/plugins a registration mechanism;
centralize third-party UI translations;
design fallback and RTL behavior as application features rather than afterthoughts.

Those principles transfer directly from Starlight to React, Next.js, server applications, component libraries, monorepos, and other TypeScript projects.

Bare-Metal Convex: Develop and Deploy with the Minimum Stack Possible

Fredy Sandoval — Wed, 12 Aug 2026 06:33:42 +0000

A reusable runbook for self-hosting Convex directly from the precompiled binary, without Docker, Podman, Nginx, or Caddy.

Tested workflow: Linux, SQLite, multiple independent Convex processes, Tailscale for administration, and Cloudflare Tunnel for public HTTPS.

Last verified: August 2026.

What this setup is

Convex can be self-hosted from a precompiled native binary. Docker is optional.

For a small deployment, the stack can be reduced to:

Development machine
├── convex-local-backend
├── Node.js + Convex CLI
└── frontend dev server

Production VM
├── convex-local-backend
├── tailscaled
├── cloudflared
└── systemd

No Docker
No Podman
No Nginx
No Caddy
No public SSH port
No public Convex ports

The Convex backend uses SQLite by default and stores its database in the process's current working directory, not beside the executable.

The dashboard is optional. It is an administrative UI and does not need to run for the application to work.

1. Download the correct Convex backend binary

Convex publishes precompiled convex-local-backend binaries in GitHub Releases.

For x86-64 Linux, use:

convex-local-backend-x86_64-unknown-linux-gnu.zip

For ARM64 Linux, use:

convex-local-backend-aarch64-unknown-linux-gnu.zip

Architecture matters. An x86-64 binary will not normally run on an ARM64 machine.

Unzip it:

unzip convex-local-backend-x86_64-unknown-linux-gnu.zip
chmod +x convex-local-backend

The ZIP contains one large executable:

convex-local-backend

A convenient per-user installation location is:

mkdir -p ~/.local/bin
mv convex-local-backend ~/.local/bin/
chmod +x ~/.local/bin/convex-local-backend

Verify:

convex-local-backend --help

The binary does not need to live beside your application data.

2. Directory model

One executable can run many independent Convex instances.

Example:

~/.local/bin/
└── convex-local-backend

~/Documents/Convex/
├── app1/
├── app2/
└── app3/

Each instance gets:

its own process
its own instance name
its own instance secret
its own admin key
its own TCP ports
its own SQLite database
its own local storage directory

The same executable can be used by all of them.

This is the important model:

same convex-local-backend executable
        |
        ├── process app1
        │   └── database/storage app1
        |
        ├── process app2
        │   └── database/storage app2
        |
        └── process app3
            └── database/storage app3

It is not one Convex process hosting multiple databases. Each deployment is a separate process.

Development setup

3. Create the first instance

Create a directory:

mkdir -p ~/Documents/Convex/app1
cd ~/Documents/Convex/app1

Generate a random instance secret:

openssl rand -hex 32

This returns a 64-character hexadecimal value.

Do not derive production instance secrets from short human passwords. A generated random 32-byte secret is the safer default.

The instance secret is extremely sensitive. Convex describes it as the root secret for the backend. Rotating it invalidates keys and sessions derived from it.

4. Create `start.sh`

For a local development instance:

nano start.sh

Example:

#!/bin/bash

cd "$(dirname "$0")" || exit 1

INSTANCE_NAME="app1"
INSTANCE_SECRET="PASTE_A_RANDOM_64_CHARACTER_SECRET_HERE"

exec convex-local-backend \
  --instance-name "$INSTANCE_NAME" \
  --instance-secret "$INSTANCE_SECRET" \
  --disable-beacon

Protect it:

chmod 700 start.sh

Then start Convex:

./start.sh

A successful first startup contains messages similar to:

Connected to SQLite at convex_local_backend.sqlite3
...
backend listening on 0.0.0.0:3210
...
backend_http_proxy listening on 0.0.0.0:3211

After startup, the directory will contain data similar to:

app1/
├── start.sh
├── convex_local_backend.sqlite3
└── convex_local_storage/
    ├── files/
    ├── modules/
    ├── search/
    ├── exports/
    └── snapshot_imports/

This proves that the database/storage follows the working directory.

About `--disable-beacon`

Self-hosted Convex includes a telemetry beacon that periodically contacts Convex.

We observed it send a request to:

https://api.convex.dev/api/self_host_beacon

Convex documents the beacon as containing minimal deployment information such as a random deployment identifier, migration version, backend Git revision, and uptime.

It is optional.

To disable it:

--disable-beacon

With the flag enabled, the local_backend::beacon startup/request lines disappear from the logs.

5. The `UDF fetch requests are unrestricted` warning

You may see:

Running without a proxy in release mode -- UDF `fetch` requests are unrestricted!

This is not a telemetry warning.

It means Convex functions that execute fetch() can make outbound network requests without a Convex-controlled filtering proxy.

For example:

await fetch("https://api.example.com/data");

can make an outbound request from the Convex host.

For local development this is usually acceptable.

For production, remember that a compromised or badly written function may be able to reach:

public Internet services
localhost services
private network services reachable from the VM

Cloudflare Tunnel protects inbound access. It does not restrict outbound fetch() calls from Convex functions.

Admin keys

6. Generate the Convex admin key

The downloaded backend release does not currently include a precompiled generate_key helper.

Convex's official direct-binary instructions use the Rust keybroker utility from the source repository.

Clone the backend source once:

git clone https://github.com/get-convex/convex-backend.git
cd convex-backend

Use the same instance secret used by the backend:

export INSTANCE_SECRET="YOUR_APP1_INSTANCE_SECRET"

Generate the key:

cargo run -p keybroker --bin generate_key -- app1 "$INSTANCE_SECRET"

The resulting admin key looks conceptually like:

app1|...

Save the complete value in a password manager or another secure secret store.

The admin key is what the Convex CLI and dashboard use to administer that backend.

Build the helper once

Cargo can produce a reusable binary:

cargo build --release -p keybroker --bin generate_key

The result should be under:

target/release/generate_key

Install it:

cp target/release/generate_key ~/.local/bin/convex-generate-key
chmod +x ~/.local/bin/convex-generate-key

Then:

convex-generate-key app1 "$INSTANCE_SECRET"

The helper binary is CPU/OS specific.

An x86-64 Linux build should not be expected to run on ARM64 Linux. The generated admin key itself, however, is just credential data and is not architecture-specific.

You usually do not need the key generator on production servers.

Connect application code

7. Point a Convex project at the local backend

Inside the actual frontend/application project:

npm install convex@latest

Create:

.env.local

For app1:

CONVEX_SELF_HOSTED_URL=http://127.0.0.1:3210
CONVEX_SELF_HOSTED_ADMIN_KEY=app1|PASTE_THE_COMPLETE_ADMIN_KEY

Do not commit .env.local.

Then:

npx convex dev

Successful output includes:

Developing against deployment:
└─ http://127.0.0.1:3210

Convex functions ready!

The CLI may also write frontend variables such as:

VITE_CONVEX_URL=http://127.0.0.1:3210
VITE_CONVEX_SITE_URL=http://127.0.0.1:3211

That is normal.

Warnings we encountered

Node localStorage experimental warning

We saw:

ExperimentalWarning: localStorage is not available because --localstorage-file was not provided.

The deployment still completed successfully. In our test this warning was not a Convex backend failure.

`/tmp` and project are on different filesystems

We saw:

Temporary directory '/tmp' and project directory ... are on different filesystems.

Convex says to use CONVEX_TMPDIR if this causes problems with filesystem watchers.

If everything works, it can be left alone.

`Filesystem changed during push, retrying...`

We saw this during npx convex dev.

Convex automatically retried and then reported:

Convex functions ready!

That was successful behavior.

8. Development process model

During active development, keep these running:

Terminal 1
./start.sh

Terminal 2
npx convex dev

And, for a Vite app:

Terminal 3
npm run dev

npx convex dev is a watcher. It continuously watches the convex/ code and pushes changes into the deployment.

It is development tooling, not the permanent production runtime.

Multiple independent apps on one machine

9. Create `app2`

Use a completely different secret and different ports.

Example allocation:

app1
backend: 3210
site:    3211

app2
backend: 3220
site:    3221

app3
backend: 3230
site:    3231

Create:

mkdir -p ~/Documents/Convex/app2
cd ~/Documents/Convex/app2

Generate a new random secret:

openssl rand -hex 32

Create start.sh:

#!/bin/bash

cd "$(dirname "$0")" || exit 1

INSTANCE_NAME="app2"
INSTANCE_SECRET="PASTE_APP2_SECRET_HERE"

exec convex-local-backend \
  --instance-name "$INSTANCE_NAME" \
  --instance-secret "$INSTANCE_SECRET" \
  --port 3220 \
  --site-proxy-port 3221 \
  --convex-origin "http://127.0.0.1:3220" \
  --convex-site "http://127.0.0.1:3221" \
  --disable-beacon

Then:

chmod 700 start.sh
./start.sh

For local development, localhost origins are appropriate.

Generate a separate admin key:

convex-generate-key app2 "THE_APP2_INSTANCE_SECRET"

Point app2's project at:

CONVEX_SELF_HOSTED_URL=http://127.0.0.1:3220
CONVEX_SELF_HOSTED_ADMIN_KEY=app2|THE_APP2_ADMIN_KEY

Then:

npx convex dev

You should see:

Developing against deployment:
└─ http://127.0.0.1:3220

Now app1 and app2 are isolated:

app1 project
    ↓
127.0.0.1:3210
    ↓
app1 Convex process
    ↓
app1 SQLite/storage


app2 project
    ↓
127.0.0.1:3220
    ↓
app2 Convex process
    ↓
app2 SQLite/storage

Stopping one process does not stop the other.

Deploying code to one does not deploy it to the other.

10. Verify processes

The simplest checks that worked in our test were:

curl -s http://127.0.0.1:3210/version; echo
curl -s http://127.0.0.1:3220/version; echo

Our precompiled build returned:

unknown
unknown

The important result was that both ports responded.

We also verified separate processes with:

ps aux | grep convex-local-backend

That showed two different PIDs and different instance/port arguments.

Security lesson: `ps` can expose the instance secret

Because the official direct-binary invocation passes:

--instance-secret <secret>

as a command-line argument, a process listing can expose that secret.

We observed exactly this with ps aux.

Therefore:

never paste production process listings without redacting secrets
use a dedicated Unix user for the Convex service in production
restrict server access
treat a secret shown in logs/chat/process listings as compromised
regenerate exposed secrets before real production use

For a production host with multiple local users, consider additional OS process-visibility hardening.

Dashboard

11. The dashboard is optional

The dashboard is not the Convex server.

The application works with only:

frontend
   ↓
convex-local-backend
   ↓
SQLite/storage

The dashboard is an administrative client:

dashboard
   ↓
convex-local-backend

It can be stopped without stopping your application.

The same dashboard build can be used to administer different deployments by using the appropriate backend URL and matching admin key.

For a production environment, keep the dashboard private where possible, for example reachable only through Tailscale.

Production deployment

12. Replace `convex dev` with a one-time deploy

Development:

npx convex dev

Production release:

npx convex deploy

We tested a successful self-hosted deployment and saw:

Deploying code to deployment:
└─ http://127.0.0.1:3210

...
Schema validation complete.
Finalizing push...

Deployed Convex functions to http://127.0.0.1:3210

After npx convex deploy finishes, there is no permanent CLI process.

The production runtime is:

convex-local-backend

The CLI is only used again when deploying changed Convex functions.

Convex's documentation explicitly notes that the backend itself does not distinguish "development" from "production"; convex dev continuously deploys while convex deploy deploys once.

13. Build the frontend separately

For Vite:

npm run build

This normally produces:

dist/

For a local production-like test you can use:

npx vite preview

But vite preview is a preview server, not the preferred permanent production web server.

In this architecture, the cleanest production option is to host the built frontend separately, for example on a static hosting platform, and keep the VM focused on Convex.

That eliminates the frontend Node process from the VM.

Production networking: Tailscale + Cloudflare Tunnel

14. Why no Nginx or Caddy is required

Cloudflare Tunnel can map public hostnames directly to local HTTP services.

For Convex, that means cloudflared can talk directly to the backend ports.

The public path becomes:

user
  ↓ HTTPS
Cloudflare
  ↓ encrypted Cloudflare Tunnel
cloudflared
  ↓ localhost HTTP
Convex

Cloudflare handles public HTTPS.

The VM does not need a public port 80 or 443.

Cloudflare Tunnel uses outbound connections initiated by cloudflared, so the origin can have public inbound traffic blocked.

Cloudflare Tunnel also supports WebSockets, which is important for Convex realtime clients.

15. Use two public Convex hostnames

A direct Convex backend normally exposes:

backend/client API: 3210
HTTP actions/site:  3211

For production, use public HTTPS origins such as:

https://convex-api.example.com
https://convex-site.example.com

Cloudflare Tunnel routes them to:

convex-api.example.com
    → http://127.0.0.1:3210

convex-site.example.com
    → http://127.0.0.1:3211

Then the production Convex process should know its public origins.

Example production start.sh:

#!/bin/bash

cd "$(dirname "$0")" || exit 1

INSTANCE_NAME="app1"
INSTANCE_SECRET="$(cat ./instance-secret)"

exec convex-local-backend \
  --instance-name "$INSTANCE_NAME" \
  --instance-secret "$INSTANCE_SECRET" \
  --port 3210 \
  --site-proxy-port 3211 \
  --convex-origin "https://convex-api.example.com" \
  --convex-site "https://convex-site.example.com" \
  --disable-beacon

Store the secret separately:

openssl rand -hex 32 > instance-secret
chmod 600 instance-secret
chmod 700 start.sh

Do not regenerate instance-secret on each boot.

The public origins matter because Convex may generate URLs that refer back to itself.

16. Cloudflare Tunnel routing

With a locally-managed tunnel, the conceptual ingress configuration is:

ingress:
  - hostname: convex-api.example.com
    service: http://127.0.0.1:3210

  - hostname: convex-site.example.com
    service: http://127.0.0.1:3211

  - service: http_status:404

Cloudflare provides the public HTTPS certificates.

The local hop can remain plain HTTP because:

cloudflared → 127.0.0.1

stays on the VM.

If your Cloudflare account has a WebSockets setting, make sure WebSockets are enabled. Cloudflare documents full WebSocket support for Tunnel.

For a second Convex app:

ingress:
  - hostname: app1-api.example.com
    service: http://127.0.0.1:3210

  - hostname: app1-site.example.com
    service: http://127.0.0.1:3211

  - hostname: app2-api.example.com
    service: http://127.0.0.1:3220

  - hostname: app2-site.example.com
    service: http://127.0.0.1:3221

  - service: http_status:404

No local reverse proxy is required just to perform hostname routing.

Add Caddy/Nginx only if you later need a feature Cloudflare Tunnel is not providing, such as complicated local rewrite logic or local load balancing.

17. Production application environment

When deploying from your development/CI machine to the production backend:

CONVEX_SELF_HOSTED_URL=https://convex-api.example.com
CONVEX_SELF_HOSTED_ADMIN_KEY=app1|PRODUCTION_ADMIN_KEY

Then:

npx convex deploy

Do not use:

http://127.0.0.1:3210

from a remote development machine; that would refer to the development machine itself.

The frontend production build should also receive the public Convex URLs appropriate to its framework, for example:

VITE_CONVEX_URL=https://convex-api.example.com
VITE_CONVEX_SITE_URL=https://convex-site.example.com

The exact frontend variable names depend on the framework and what the Convex CLI/project generated.

Tailscale and firewall

18. Use Tailscale for administration

Tailscale lets you keep SSH and administrative services off the public Internet.

Typical administration path:

your laptop
   ↓ Tailscale
production VM
   ├── SSH
   ├── logs
   └── private dashboard

Tailscale's current documentation says most installations do not require manually opening an inbound firewall port. When direct peer-to-peer connectivity is not possible it can fall back to relays.

Before blocking public SSH, verify that you can log in using the VM's Tailscale IP.

Get it with:

tailscale ip -4

Test:

ssh user@100.x.y.z

Only after that should you remove public SSH access.

19. UFW model for the VM

A minimal model:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow in on tailscale0
sudo ufw enable

Review:

sudo ufw status verbose

With Cloudflare Tunnel, you do not need public UFW rules for:

assuming administration is through Tailscale and all public app traffic comes through cloudflared.

Cloudflare documents that Tunnel can work with inbound traffic blocked because cloudflared creates outbound-only connections.

Do not lock yourself out: verify Tailscale SSH/network access before deleting an existing public SSH rule.

systemd production service

20. Keep Convex running without a terminal

Create a service unit such as:

/etc/systemd/system/convex-app1.service

Example:

[Unit]
Description=Convex app1 backend
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=convex
WorkingDirectory=/srv/convex/app1
ExecStart=/srv/convex/app1/start.sh
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

The application directory could be:

/srv/convex/app1/
├── start.sh
├── instance-secret
├── convex_local_backend.sqlite3
└── convex_local_storage/

Then:

sudo systemctl daemon-reload
sudo systemctl enable --now convex-app1

Check:

systemctl status convex-app1

Logs:

journalctl -u convex-app1 -f

For app2, create another unit using its own directory and ports.

Resource usage findings

21. What we observed

In our small idle test:

App	Approx. RAM
`convex-tutorial` production-like process set	~276 MB
`presence-typing-indicator` production-like process set	~348 MB
Combined	~624 MB

Idle CPU was negligible.

With duplicate development stacks using convex dev, measured combined usage had previously been roughly 1.5 GB.

Moving to:

convex-local-backend
+
one-time convex deploy
+
built frontend

reduced the observed idle footprint substantially.

These are environment-specific measurements, not guaranteed Convex requirements.

For real capacity planning, measure:

VM baseline before apps
incremental memory after each Convex instance
real traffic
search/vector workloads
file storage
scheduled jobs
OS/cache usage

PSS is preferable to blindly summing RSS when possible.

For a 2 GB VM, a conservative starting target is usually fewer applications than the mathematical maximum. Leave headroom for Linux, Tailscale, cloudflared, filesystem cache, traffic bursts, and maintenance operations.

Important production notes

22. SQLite is the minimum, not necessarily the final database architecture

Convex defaults to SQLite for self-hosting and recommends starting with the basic configuration.

For a mini production environment this can be useful because it eliminates a separate database server.

However, production requirements eventually determine whether you should move to Postgres/MySQL and/or external object storage.

At minimum, back up:

convex_local_backend.sqlite3
convex_local_storage/

and test restoration.

Do not assume a copied live SQLite file is a valid backup without using an appropriate consistent-backup procedure.

23. Do not confuse three different kinds of environment variables

Backend process configuration

Used to configure the convex-local-backend process itself.

In this runbook we mostly use explicit flags in start.sh.

Convex CLI self-hosted connection

Used by your source project:

CONVEX_SELF_HOSTED_URL=...
CONVEX_SELF_HOSTED_ADMIN_KEY=...

These tell npx convex dev and npx convex deploy which self-hosted backend to administer.

Convex function environment variables

Application secrets such as third-party API keys belong inside the Convex deployment environment and are accessed by Convex functions.

These are conceptually separate from the instance secret and admin key.

Common mistakes from this test

24. Mistakes to avoid

Mistake: thinking the dashboard is required

It is not. It is an admin UI.

Mistake: leaving `npx convex dev` running in production

Use:

npx convex deploy

for a one-time deployment.

Keep only convex-local-backend running.

Mistake: using one secret for multiple apps

Each independent backend should have its own:

instance secret
admin key
ports
database/storage directory

Mistake: running two instances on the same ports

Allocate separate pairs:

3210/3211
3220/3221
3230/3231

Mistake: regenerating `INSTANCE_SECRET` every boot

Do not do this.

The same deployment must keep the same instance secret unless you intentionally rotate it.

Mistake: exposing secrets with `ps`

Direct CLI arguments can be visible in process listings.

Do not publish unredacted ps output.

Mistake: assuming `/version` must display a release number

Our precompiled backend returned:

unknown

while functioning correctly.

Use it mainly as a reachability/health signal unless your build provides a meaningful version string.

Mistake: thinking Cloudflare Tunnel restricts Convex `fetch()`

It does not.

Tunnel handles inbound/public access. Convex UDF fetch() is outbound traffic.

Mistake: keeping localhost origins in production

Local development:

http://127.0.0.1:3210
http://127.0.0.1:3211

Production behind Cloudflare:

https://convex-api.example.com
https://convex-site.example.com

The production backend should know its public origins.

Mistake: assuming Vite preview is the final production host

vite preview is useful to test a production build.

For a real deployment, host the static build on a proper static host. If the frontend is hosted away from the Convex VM, the VM uses less RAM.

Final architecture

Development

Developer PC

app source
   |
   ├── npm run dev
   │      ↓
   │   Vite frontend
   │
   └── npx convex dev
          ↓
     localhost:3210
          ↓
convex-local-backend
          ↓
SQLite + local storage

Production

                         ┌─────────────────────┐
                         │   Static frontend   │
                         │  (separate hosting) │
                         └──────────┬──────────┘
                                    |
                                    | HTTPS
                                    v
                                 Browser
                                    |
                                    | HTTPS / WebSocket
                                    v
                              Cloudflare edge
                                    |
                             Cloudflare Tunnel
                                    |
                                    v
                            production VM
                     ┌──────────────┼──────────────┐
                     │              │              │
                 tailscaled     cloudflared    systemd
                     │              │              │
                 private admin      │        convex-local-backend
                                    │              │
                                    ├── :3210 API  │
                                    └── :3211 site │
                                                   │
                                              SQLite/storage

Public inbound firewall:
DENY

Administrative access:
Tailscale

Public application access:
Cloudflare Tunnel

This is the minimum production stack we were aiming for:

Convex binary
+ SQLite/local storage
+ systemd
+ Tailscale
+ Cloudflare Tunnel

No container runtime and no local reverse proxy are inherently required.

Quick rebuild checklist

If rebuilding from zero:

Download the correct convex-local-backend architecture.
Put it in ~/.local/bin or a system binary directory.
Create a dedicated directory for each instance.
Generate a random 32-byte instance secret.
Create start.sh.
Assign unique ports for each instance.
Start the backend and confirm SQLite/storage paths.
Build convex-generate-key once from the Convex source repository.
Generate a unique admin key for each backend.
Put CONVEX_SELF_HOSTED_URL and CONVEX_SELF_HOSTED_ADMIN_KEY in the application project's uncommitted environment file.
Develop with npx convex dev.
Release backend functions with npx convex deploy.
Build the frontend separately.
On production, set Convex's public origins to the Cloudflare HTTPS hostnames.
Route the API/site hostnames through Cloudflare Tunnel to the local Convex ports.
Verify Cloudflare WebSockets are enabled.
Install Tailscale and verify remote access through the tailnet.
Deny public inbound traffic and allow the tailscale0 interface.
Run Convex under systemd.
Back up the SQLite database and local storage, and test restores.

Sources

This runbook combines direct testing with current official documentation. Re-check these sources before a future major upgrade because self-hosted Convex is actively developed.

Convex self-hosting README: https://github.com/get-convex/convex-backend/blob/main/self-hosted/README.md
Convex: running the precompiled binary directly: https://github.com/get-convex/convex-backend/blob/main/self-hosted/advanced/running_binary_directly.md
Convex self-hosted Fly guide, including convex dev vs convex deploy and public origins: https://github.com/get-convex/convex-backend/blob/main/self-hosted/advanced/fly/README.md
Convex backend repository/self-hosting notes and beacon description: https://github.com/get-convex/convex-backend
Cloudflare Tunnel overview: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/
Cloudflare published applications: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/routing-to-tunnel/
Cloudflare Tunnel WebSocket support: https://developers.cloudflare.com/cloudflare-one/faq/cloudflare-tunnels-faq/
Tailscale firewall-port guidance: https://tailscale.com/docs/reference/faq/firewall-ports
Tailscale UFW server-lockdown guide: https://tailscale.com/docs/how-to/secure-ubuntu-server-with-ufw

How to Compile and Run Convex Locally from Source

Fredy Sandoval — Wed, 12 Aug 2026 03:41:35 +0000

This guide explains how to build and run the Convex backend from source on
Arch Linux. It is written for developers who are new to the repository and
want a reliable local development setup.

The commands below assume that you are working from the root of the cloned
repository:

cd ~/Documents/OpenSource/convex-backend

What is in this repository?

Convex is an open-source reactive backend and database platform. Applications
define database functions in TypeScript, while the backend provides database
storage, queries, mutations, actions, file storage, scheduled jobs,
authentication, synchronization, search, and related services.

The repository has two main areas:

crates/ contains the Rust backend workspace. The local_backend crate produces the convex-local-backend executable.
npm-packages/ contains the JavaScript and TypeScript monorepo, managed by pnpm and Turborepo. It includes the Convex client, CLI, dashboards, runtime packages, tests, and demos.

There is also a top-level demo/ directory containing a separate Vite/React
example, plus self-hosted/ documentation for deployment and prebuilt
binary usage.

1. Install Arch Linux system dependencies

Install the compiler toolchain and native libraries required by Rust and the
JavaScript tooling:

sudo pacman -Syu --needed \
  base-devel \
  git \
  curl \
  openssl \
  libsodium \
  rocksdb \
  snappy \
  pkgconf \
  python \
  rustup

base-devel supplies common build tools such as GCC, Make, and Binutils.

You should also have fnm installed. The repository does not require NVM;
fnm is sufficient for managing Node.js versions. On Arch Linux it can be
installed with:

sudo pacman -S --needed fnm

2. Configure fnm and install the required Node.js version

Convex pins Node.js to version 22.22.2 in .nvmrc. Configure fnm for the
current Bash session:

eval "$(fnm env --shell bash)"
fnm install 22.22.2 --use
fnm default 22.22.2

Check that the correct version is active:

node --version
npm --version

The expected Node.js version is:

v22.22.2

To configure fnm automatically for future Bash sessions, add this line to
~/.bashrc:

eval "$(fnm env --use-on-cd --shell bash)"

Then reload Bash:

source ~/.bashrc

If you use Zsh instead, add the equivalent line to ~/.zshrc:

eval "$(fnm env --use-on-cd --shell zsh)"

3. Install the repository-pinned development tools

Convex uses mise to install and manage several exact tool versions,
including Just, CMake, Protocol Buffers, jq, uv, and Rust cargo utilities.

Install mise using its official installer:

curl https://mise.run | sh

Mise will give you instructions on how to add it to your shell for example:

mise: installed successfully to /home/YourUser/.local/bin/mise
mise: run the following to activate mise in your shell:
echo "eval \"\$(/home/YourUser/.local/bin/mise activate zsh)\"" >> "/home/YourUser/.zshrc"

Install the versions declared by mise.toml:

mise install

The repository currently pins these important tools:

Tool	Version
Node.js	`22.22.2`
Rust	`nightly-2026-06-28`
pnpm	`10.34.5`
Turborepo	`2.10.5`
Just	`1.52.0`
CMake	`3.31.12`
protoc	`21.12`
uv	`0.11.5`
jq	`1.8.1`

Rust automatically uses the toolchain selected by rust-toolchain when you
run commands inside this repository. Verify it with:

rustc --version
cargo --version

If Rust reports that the toolchain is not installed, install it explicitly:

rustup toolchain install nightly-2026-06-28

4. Install the JavaScript tooling

The scripts/ package contains the repository's pinned versions of pnpm,
Turborepo, dprint, and related scripts. Install them with npm:

npm clean-install --prefix scripts

Then install the locked JavaScript workspace dependencies:

just install-js

The lockfile is npm-packages/pnpm-lock.yaml. Keep the lockfile intact and
prefer the repository commands over installing random global versions of
pnpm or Turborepo.

5. Compile the backend from source

The local backend is the Rust binary named convex-local-backend. To compile
it directly in debug mode:

cargo build --locked -p local_backend --bin convex-local-backend

The compiled binary will be under Cargo's target/ directory.

For a release build:

cargo build --release --locked -p local_backend --bin convex-local-backend

The first build can take a long time. Some dependencies include V8 and
Chromium-related source repositories, so Cargo may need to download and
prepare a large dependency graph before Rust compilation begins.

6. Run the backend locally

The recommended development command is:

just run-local-backend

This starts the backend from source and creates the local instance credentials
when necessary.

The default local endpoints are:

Service	Address
Convex backend	`http://127.0.0.1:3210`
HTTP Actions proxy	`http://127.0.0.1:3211`

Local state is stored in:

convex_local_backend.sqlite3
convex_local_storage/

To pass an option to the backend, place it after the Just command, for
example:

just run-local-backend --disable-beacon

To remove local backend state and start over:

just reset-local-backend

Keep the backend terminal running while using the CLI or a demo. Stop it with
Ctrl+C when finished.

7. Build the JavaScript and TypeScript monorepo

Build all workspace packages and their dependencies with Turborepo:

just turbo run build

To build one package and its dependencies, use a filter:

just turbo run build --filter=convex...

The ... means “also build the dependencies of this package.”

For package-level development, for example:

cd npm-packages/convex
npm run build
npm run lint
npm run format-check
npm run typecheck
npm test

Return to the repository root when using the root-level Just commands:

cd ../..

8. Run the included tutorial demo against the local backend

Use two terminals.

In terminal 1, start the backend:

cd ~/Documents/OpenSource/convex-backend
just run-local-backend

In terminal 2, install the JavaScript workspace if you have not already done
so, then start the tutorial's Convex development process:

cd ~/Documents/OpenSource/convex-backend
just install-js
cd npm-packages/demos/tutorial
just convex dev

The repository's just convex helper configures the local backend URL and
uses the generated local admin key.

There is also a separate top-level Vite/React demo. It is not part of the
pnpm workspace, so install its dependencies separately:

cd ~/Documents/OpenSource/convex-backend/demo
npm install
npm run dev

9. Useful development commands

Rust formatting, tests, and linting

cargo fmt
cargo test
cargo test -p local_backend
cargo clippy
cargo nextest run --no-run --profile ci

JavaScript formatting, tests, and linting

just turbo run build
cd npm-packages/convex
npm test
npm run lint
npm run format-check
npm run typecheck
npm run test-esm

Local Convex CLI helpers

From the repository root:

just convex dev
just convex data
just convex env
just convex logs
just convex import
just convex export

10. Troubleshooting

`node --version` shows the wrong version

Reload fnm and select the pinned version:

eval "$(fnm env --shell bash)"
fnm install 22.22.2 --use

`just: command not found`

Ensure mise is on PATH, then install the repository tools:

export PATH="$HOME/.local/bin:$PATH"
mise install

Cargo cannot download dependencies

The backend has large Git-based dependencies. Confirm that Git and network
access work, then retry:

git --version
cargo build --locked -p local_backend --bin convex-local-backend

JavaScript installation fails with a DNS or registry error

Retry after confirming npm connectivity:

curl -I https://registry.npmjs.org/
npm clean-install --prefix scripts

The demo cannot connect to Convex

Make sure just run-local-backend is still running in another terminal and
that the backend is listening on port 3210:

curl http://127.0.0.1:3210

Start with a completely fresh local backend

This removes only the repository's local backend state:

just reset-local-backend
just run-local-backend

Quick-start summary

Once Arch Linux prerequisites are installed, the normal workflow is:

cd ~/Documents/OpenSource/convex-backend
eval "$(fnm env --shell bash)"
fnm use 22.22.2 --install-if-missing
export PATH="$HOME/.local/bin:$PATH"
mise install
npm clean-install --prefix scripts
just install-js
just run-local-backend

Then use a second terminal for the tutorial demo or JavaScript package
development.

Did you know you don't need a Raspberry PI to build a NAS, you can make a virtual nas instead.

Fredy Sandoval — Thu, 06 Aug 2026 05:53:56 +0000

Fredy Sandoval

Aug 6

Making a Virtual NAS with virt-manager, OpenMediaVault, and Tailscale

#nas #virtmanager #openmediavault #tailscale

6 min read

Making a Virtual NAS with virt-manager, OpenMediaVault, and Tailscale

Fredy Sandoval — Thu, 06 Aug 2026 05:52:41 +0000

TL;DR
This is a practical, guide to turning a spare disk into a NAS by running OpenMediaVault (OMV) inside a KVM virtual machine. It covers the whole path: preparing the disk, installing OMV, passing the disk through correctly (including the traps that are easy to fall into), sharing files over SMB, mounting the share on your host, and reaching your NAS from your phone with Tailscale.

Tools used

virt-manager (libvirt/KVM/QEMU) — the virtualization layer
OpenMediaVault (OMV) — the NAS operating system
btrfs — filesystem, chosen for future expandability
Samba (SMB/CIFS) — file sharing protocol
Tailscale — secure remote access to the NAS from anywhere
cifs-utils — for mounting the share on Linux

Overview

The VM needs two disks:

A small virtual disk (qcow2, ~16–20 GB) for the OMV operating system itself
A physical disk, passed through directly to the VM, for your actual data

Keeping these separate matters — OMV refuses to store shared data on its own system disk, and passthrough gives near-native performance on the data disk.

Important order of operations: install OMV with only the OS disk attached, and add the physical data disk afterward. If both disks are present during install, OMV's partitioner can fail to show a proper disk-selection screen and loop on a "No root file system is defined" error instead. Attaching the data disk after install avoids this entirely.

Step 1: Place the OMV ISO where libvirt can read it

Download the ISO from https://www.openmediavault.org/download.html.

If virt-manager uses the system session (the default), QEMU runs as its own user and often can't read files inside your home folder. Avoid permission errors by moving the ISO into the default pool:

sudo mkdir -p /var/lib/libvirt/images
sudo mv ~/Downloads/openmediavault_*.iso /var/lib/libvirt/images/

Step 2: Identify your target disk (don't attach it yet)

Find the disk with lsblk:

lsblk -o NAME,SIZE,MODEL,MOUNTPOINTS

Unmount anything mounted from it:

sudo umount /dev/sdX1   # whatever partitions are mounted

Also grab its stable identifier now, so it's ready later — /dev/sdX names can change across reboots, so use the by-id path instead:

ls -l /dev/disk/by-id/ | grep -v part

Note the entry that matches your disk (e.g. ata-YourDiskModel_SerialNumber). You won't attach this disk to the VM until after OMV is installed.

Step 3: Create the VM

virt-manager → File → New Virtual Machine
Local install media (ISO) → select the OMV ISO
Guest OS: Debian 12 (OMV 7 is based on it)

RAM: 2048–4096 MB, CPUs: 2 is enough

Create a ~16–20 GB virtual disk — this becomes the OS disk only (do not attach the physical data disk at this stage)

Name the VM (e.g. omv), check "Customize configuration before install" → Finish

Step 4: Install OMV

Boot the VM and run through the installer. Since only the OS disk is present, the partitioner will offer just one option — select it, let it guide-partition automatically, set a root password, and complete the install.

At the console login, the username is root, with the password you set during install — this is separate from the OMV web interface login you'll use later.

Once you reach the login prompt successfully, shut the VM down:

sudo virsh shutdown omv

Step 5: Attach the physical data disk

Now that OMV is installed, attach the real disk.

Attach it via the command line — this avoids a common GUI mistake where selecting "custom storage" and typing just the disk name (without the full path) causes virt-manager to silently create a brand-new empty virtual disk file instead of using your real disk:

sudo virsh attach-disk omv /dev/disk/by-id/ata-YOUR-DISK-ID vdb --targetbus virtio --persistent

If you prefer the GUI: Add Hardware → Storage → "Select or create custom storage", then paste the full absolute path (/dev/disk/by-id/...) into the field, bus type VirtIO.

Double-check it worked by opening the VM's XML (Edit → XML, or virsh dumpxml omv). You want:

<disk type="block" device="disk">
  <driver name="qemu" type="raw"/>
  <source dev="/dev/disk/by-id/ata-YOUR-DISK-ID"/>
  <target dev="vdb" bus="virtio"/>
</disk>

If instead you see type="file" and a source file="..." pointing somewhere in your home folder, that's the mistake above — remove the disk, delete the accidental file it created, and reattach using the full path.

Boot the VM back up.

Step 6: Log into the web UI

Find the VM's IP:

ip a

Browse to http://<vm-ip>. Default login: admin / openmediavault — change the password immediately.

Step 7: Wipe and format the data disk (from OMV, not the host)

Storage → Disks → select your data disk → Wipe (quick wipe is fine)
Storage → File Systems → Create
- Select the disk
- Filesystem: btrfs
- Profile: single (this is the correct choice for one disk — you can convert to a mirror later without reformatting, once you add a second disk)
Mount it when prompted, then apply the pending configuration (the yellow banner at the top — nothing takes effect until you click Apply)

Step 8: Create a shared folder, user, and SMB share

Shared folder:
Storage → Shared Folders → Create → name it (e.g. Documents), pick your btrfs filesystem, save, apply.

User:
Users → Users → Create → set username/password, add to the users group, shell nologin, leave SSH keys empty. This user is only for share access — don't reuse the admin account.

Enable SMB:
Services → SMB/CIFS → Settings → check Enabled, leave Workgroup as WORKGROUP, uncheck Home directories, minimum protocol SMB2. Save.

Create the share:
Services → SMB/CIFS → Shares → Create → pick your shared folder, Public: No, Browseable: checked, Enable recycle bin: checked. Save → Apply.

Test from the host:

smbclient -L //<vm-ip> -U yourusername

You should see your share listed (alongside IPC$).

Step 9: Mount the share on your host

For it to behave like a real folder (so touch, editors, and every app work normally):

sudo pacman -S cifs-utils   # or apt install cifs-utils

sudo mkdir -p /mnt/nas
sudo mount -t cifs //<vm-ip>/Documents /mnt/nas \
  -o username=yourusername,uid=$(id -u),gid=$(id -g)

To make this permanent and automatic, store the password in a credentials file and use a systemd automount in /etc/fstab, so the share connects on demand and doesn't hang at boot if the VM isn't running yet:

sudo nano /etc/samba-credentials

username=yourusername
password=yourpassword

sudo chmod 600 /etc/samba-credentials

/etc/fstab line:

//<vm-ip>/Documents  /mnt/nas  cifs  credentials=/etc/samba-credentials,uid=1000,gid=1000,file_mode=0664,dir_mode=0775,noauto,x-systemd.automount,x-systemd.idle-timeout=60,_netdev  0  0

sudo systemctl daemon-reload

Note: mounted network shares don't show up in lsblk (that only lists block devices). Check with findmnt /mnt/nas or mount | grep cifs instead.

Step 10: Reach your NAS from your phone with Tailscale

NAT networking (virt-manager's default) only lets the host reach the VM. Rather than reconfigure networking with bridges, Tailscale tunnels through NAT with no router or bridge setup needed, and works from anywhere, not just at home.

On the VM:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Open the printed login URL, sign in, then check the assigned address:

tailscale ip -4

On your phone: install the Tailscale app, log into the same account, enable the VPN toggle.

For automatic backup (Android): install FolderSync, add an SMB account pointed at the VM's Tailscale IP, and create a folder pair (e.g. DCIM/Camera → Documents/PhoneBackup, sync direction "To remote folder"). Schedule it to run daily.

Tip: enable MagicDNS in the Tailscale admin console so you can use a hostname instead of memorizing an IP.

Keeping it running

Make the VM start automatically with the host:

sudo virsh autostart omv

Planning ahead for redundancy

Because the data disk was formatted as btrfs, single profile, adding redundancy later is a live, in-place operation — no reformatting or data migration:

Attach the new disk to the VM the same way as Step 5 (by-id path, virsh attach-disk)
Wipe it from OMV's disk manager
Convert to a mirror:

btrfs device add /dev/vdc /srv/dev-disk-by-uuid-xxxx
btrfs balance start -dconvert=raid1 -mconvert=raid1 /srv/dev-disk-by-uuid-xxxx

Your data is then mirrored across both disks. Note this protects against a disk failure — it isn't a substitute for backups against accidental deletion.

Summary of pitfalls this guide avoids

ISO unreadable by QEMU → placed in /var/lib/libvirt/images
Installer failing to show disk selection → install OS with only the OS disk attached; attach the data disk afterward
Typing a disk name without its full path → accidentally creates a blank virtual disk file instead of using the real disk
Choosing the wrong filesystem for future growth → btrfs single, upgradeable to raid1 without reformatting
NAS only reachable from the host → Tailscale, no router/bridge configuration required

I'm developing a tool called showsignature [critics wanted]

Fredy Sandoval — Sat, 11 Jul 2026 03:52:35 +0000

Hello Dev Community I'm developing a tool called showsignature I've been using it to develop itself since the beginning and I've use it on other projects tool, and just feels right.

It started as specific tool I needed for a particular problem at the beginning, but it was so useful that I adopted it entirely in my code environment with other project, and I took features and added others depending on the need.

I code mostly with Pi, but I've used Opencode, Codex and Claude code too, and is very useful there as well.

The tools if fully open-source, and I believe it may be useful to other people too, specially in this times where tokes are becoming more and more expensive each time, and code bases grow and grow, with features here and there.

It only has 4 dependencies commander, globby, typescript and zod.

Here is a benchmark for those wondering if this tool is really useful:

For me those results are very impressive because they represent a reduction on %60 token usage and increase in success rate for tasks.

The way it works is pretty simple:

showsignature map  [OPTION]... [PATH]...
showsignature read [OPTION]... <FILE>

It has two commands:

map — structural overview: signatures and other extracted entries. Inspect [PATH] operands—files or directory paths—using the current directory by default.

read — literal windowed read of exactly one file, with an optional structural outline around the window for orientation.
Running showsignature with no command prints help and exits with code 1.

For Pi and Opencode it works as a native tool call, for Claude code and Codex is used as a bash command.

So if you want to give a try, I'm fully opened to critics, bug reports and pull requests, if you haven't contribute to opensource and need that for your resume, you're also welcome.

vibe-testing.¹ is also welcome.

https://github.com/FredySandoval/showsignature

Vibe-testing: asking your agent to use a tool or command exhaustively until it find a strange behavior or bug and report. ↩

A Pi extension to show a new Pi logo every time you open Pi.

Fredy Sandoval — Tue, 12 May 2026 08:03:55 +0000

People of pi, I Just published a Pi extension to show a new Pi logo every time you open Pi.

What you get

Random Pi logo on startup
Small animation when Pi opens a new session
Built-in shortcut help in the header
Responsive layout for narrow terminals

FredySandoval / pi-logo

A Pi extension to show a new Pi logo every time you open Pi.

pi-logo

A Pi extension to show a new Pi logo every time you open Pi.

Install

pi install npm:pi-logo

Restart Pi.

What you get

Random Pi logo on startup
Small animation when Pi opens a new session
Built-in shortcut help in the header
Responsive layout for narrow terminals

How to use?

Just open Pi! and enjoy a new logo everytime you open Pi.

Try without installing

pi -e npm:pi-logo

Remove

pi remove npm:pi-logo

█▀█  pi-logo v1.0.0
█▀ █ Oh by the way, which one’s Pink?

View on GitHub

Terminal Tip 🤩 fcopy, fcut, fpaste

Fredy Sandoval — Sun, 15 Mar 2026 02:47:00 +0000

If you are like me and love the terminal, start using fcopy, fcut, fpaste

how does it work, instead of copying through a file explorer, just do:

$ fcopy some/file/
$ fcopy other/file/image.png

then open other terminal and do:

$ fpaste

fcopy() {
  if [ "$#" -eq 0 ]; then
    echo "fcopy: nothing to copy"
    return 1
  fi

  tmp="$(mktemp)"
  printf 'copy\n' > "$tmp"

  for item in "$@"; do
    if [ -e "$item" ]; then
      abs="$(realpath "$item")"
      printf '%s\n' "$abs" >> "$tmp"
      echo "copied to clipboard: $abs"
    else
      echo "fcopy: not found: $item" >&2
    fi
  done

  mv "$tmp" ~/.fileclip
}

fcut() {
  if [ "$#" -eq 0 ]; then
    echo "fcut: nothing to cut"
    return 1
  fi

  tmp="$(mktemp)"
  printf 'move\n' > "$tmp"

  for item in "$@"; do
    if [ -e "$item" ]; then
      abs="$(realpath "$item")"
      printf '%s\n' "$abs" >> "$tmp"
      echo "cut to clipboard: $abs"
    else
      echo "fcut: not found: $item" >&2
    fi
  done

  mv "$tmp" ~/.fileclip
}

fpaste() {
  [ -f ~/.fileclip ] || { echo "fpaste: file clipboard is empty"; return 1; }

  mode="$(head -n1 ~/.fileclip)"
  count=0

  while IFS= read -r src; do
    [ -n "$src" ] || continue

    if [ ! -e "$src" ]; then
      echo "fpaste: source no longer exists: $src" >&2
      continue
    fi

    if [ "$mode" = "move" ]; then
      if mv -- "$src" .; then
        echo "moved: $src -> $PWD/"
        count=$((count + 1))
      else
        echo "fpaste: failed to move: $src" >&2
      fi
    else
      if cp -a -- "$src" .; then
        echo "pasted: $src -> $PWD/"
        count=$((count + 1))
      else
        echo "fpaste: failed to paste: $src" >&2
      fi
    fi
  done < <(tail -n +2 ~/.fileclip)

  echo "done: $count item(s)"
}

If you like VS Code REST Client, you're going to love LAZYREQUEST

Fredy Sandoval — Wed, 25 Feb 2026 01:41:04 +0000

If you like VS Code REST Client, you're going to love LAZYREQUEST

You already know the best format for API testing: a plain .http file.

What you probably don't have is a dead-simple way to run those files from the terminal (and CI), validate the responses you expect, and get a clean PASS/FAIL signal without adopting an entire new testing framework.

Meet LAZYREQUEST: a lightweight, minimal API Testing Client CLI tool inspired by VS Code REST Client syntax. It recursively discovers .http and .rest files, sends the requests, and compares actual responses against the expected responses you declare in the same template.

Site | npm | GitHub

If you've ever thought:

"My API smoke tests should be as easy as writing an HTTP request."
"I want contract-ish checks without standing up a whole test harness."
"Why does 'try this endpoint' live in Slack instead of in the repo?"

This is for YOU!.

TL;DR

Write requests the same way you already do in VS Code REST Client: method, URL, headers, body.
Optionally declare an expected response block right in the file (status + headers + body).
Run lazyrequest on a folder. It finds everything, executes fast (concurrent by default), and tells you what broke.
No new syntax.
No heavy GUI.
No learning curve.
No Postman tab explosion.

Just .http files. And power.

No collections. No click-ops. No "where did we store the latest curl command?"

The Problem Nobody Talks About

Let's say you are working on a API and you need to test it, you can quickly write a .http file with something like:

GET http://localhost:8080/health

You can see it's output. It works. It’s clean. It’s readable.

But then:

You need CI integration
You want automated assertions
You want folder-wide execution
You want concurrent runs
You don’t want a browser UI

Suddenly you’re installing a whole testing framework. Yikes...

API Testing: when testing becomes a torture

Most teams already have "API tests" scattered across:

random curl commands in docs
unreadable Postman collections everybody is affraid to touch
a half-finished test suite that only one person understands

LAZYREQUEST makes the happy path boring:

your requests live in the repo as .http / .rest
your expectations live next to the request (when you want assertions)
your terminal becomes the source of truth

A real example (request + expected response)

What If Your .http Files Became Your Test Suite?

That’s exactly what LAZYREQUEST does.

@baseUrl = http://localhost:8080

###
POST {{baseUrl}}/users HTTP/1.1
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

###
# Expected response
HTTP/1.1 201 Created
Content-Type: application/json
Location: {{baseUrl}}/users/123

{"ok":true,"id":123}

Then run:

$ lazyrequest

And you instantly know:
✓ Passed/Failed Status
✓ Headers correct
✓ JSON structure correct

Or exactly what failed.

Now your repo contains something you can:

review in a PR
run locally
run in CI
keep up-to-date without ceremony

Try It. Break It. Star It. ⭐

Installation:

npm i -g lazyrequest

Or clone + build with Bun:

git clone https://github.com/FredySandoval/lazyrequest.git
bun build ./src/index.ts --compile --minify --outfile lazyrequest --target bun

Or download the binary from GitHub releases.
https://github.com/FredySandoval/lazyrequest

npm:
https://www.npmjs.com/package/lazyrequest

Final Thought

The best tools don’t invent new syntax.
They unlock the power of what you’re already using.
LAZYREQUEST doesn’t replace your workflow.
It upgrades it. 🚀

Google OAuth2 for Dummies

Fredy Sandoval — Mon, 12 Jun 2023 18:07:27 +0000

The Full code is at the bottom.

TLDR: In this tutorial we will Authenticate an Application using Google OAuth2. It loads credentials from a local JSON file, creates an OAuth2 client with those credentials, and sets up a few HTTP routes to handle the authentication process.

Questions to be answered:

1. How authenticate an app using Google OAuth2 in NodeJS?

You use the googleapis npm package to create an OAuth2 client with your app's credentials. Generate an authorization URL and redirect users there to grant your app permissions. When they're redirected back to your app, exchange the "code" they bring for access and refresh tokens.

2. How do you load credentials from a JSON file in Google APIs?

You can use the fs module's readFileSync function to read the contents of the file. Then, use JSON.parse to parse the contents into a JavaScript object.

3. What are the Google API scopes?

Scopes define the permissions your app is requesting from users. This script requests permission to send Gmail messages on the user's behalf.

PART 1

Creating credentials

a. Go to Google Console > Credentials
https://console.cloud.google.com/apis/credentials

b. Create a new Credential of type OAuth client ID

c. Select type Desktop and give any name you want

d. Save the JSON file (client_secret_xxx…) in the root folder of
the project

IMPORTANT!

You must add the email addresses of the people that will use
the application, including yours. Otherwise that person won’t
be able to use the application.

You also must modify the JSON secret file (the file you just
downloaded "client_secret_xxx…")
At the end of the file you will find “redirect_uris”, you need to
modify it like this:

PART 2

We're going to break down a piece of code that allows your application to interact with Google APIs using OAuth2 for authentication. This script involves several important Node.js modules like googleapis, fs, path, and express. Let's get started!

First off, install the necessary packages.

npm init -y
npm install express googleapis

now let's import some essential modules:

const { google } = require('googleapis');
const fs = require('fs');
const path = require('path');

google is part of googleapis, which lets us interact with Google's services. fs is a built-in Node.js module to work with the file system, and path helps us with file paths.

Now, we define some constants:

const CREDENTIALS_FOLDER  = './'; // location of credentials
const SCOPES              = ['https://www.googleapis.com/auth/gmail.send'];

CREDENTIALS_FOLDER is the location of our Google API credentials file. SCOPES is an array that specifies what permissions our application requests from users. Here, we're asking to send Gmail messages on behalf of the user.

The next part of the script involves loading our Google API credentials:

let credentials;
try {
  const files = fs.readdirSync(CREDENTIALS_FOLDER);
  const credentialsFile = files
    .find(file => file.startsWith('client_secret_') && file.endsWith('.json'));
  const credentialsPath = path.join(__dirname, CREDENTIALS_FOLDER, credentialsFile);
  const file = fs.readFileSync(credentialsPath, 'utf8');
  credentials = JSON.parse(file);
} catch (error) {
  console.log("unable to read file, can't continue");
}

This script looks for a file that starts with client_secret_ and ends with .json (this is your Google API credentials file). It then reads the file and parses it as JSON. If something goes wrong (like if the file doesn't exist), it logs an error message.

Next, we validate our credentials:
But why? it is very common that we or somebody loads the incorrect credentials type, Google has different credentials, and validating we have the right ones will save hours of debugging.

const REQUIRED_CREDENTIALS_PROPERTIES = [
  'client_id', 'project_id', 'auth_uri', 'auth_provider_x509_cert_url', 'token_uri', 'client_secret', 'redirect_uris'
];
REQUIRED_CREDENTIALS_PROPERTIES.forEach(prop => {
  if (!(prop in credentials.installed)) 
    throw new Error(`Property ${prop} not found in credentials`);
});

We have a list of all the properties that should be in our credentials object, and we make sure that each one is there. If not, we throw an error.

Now we create an OAuth2 client:

const { installed: { client_id, client_secret, redirect_uris } } = credentials;
const oAuth2Client = new google.auth.OAuth2(client_id, client_secret, redirect_uris[0]);
let authUrl = oAuth2Client.generateAuthUrl({
  access_type: 'offline',
  scope: SCOPES
});

We pull out the necessary parts of our credentials and create an OAuth2 client. We then generate a URL (authUrl) where users will grant our application the permissions we requested.

Next, we set up an Express application:

const express = require('express');
const app = express();

Express is a framework that makes it easier to handle HTTP requests and responses in Node.js.

We define three routes. The first ('/') sends users to the authUrl we generated earlier:

app.get('/', (req, res) => {
  res.send(`<a href="${authUrl}">Authorize</a>`);
});

The second (/oauth2callback) is the "callback URL". After users grant permissions, Google redirects them here with a special "code". We exchange that code for access and refresh tokens, which allow us to make authorized requests on behalf of the user:

app.get('/oauth2callback', async (req, res) => {
  const { code } = req.query;
  const { tokens } = await oAuth2Client.getToken(code);
  oAuth2Client.setCredentials(tokens);
  res.redirect('/authenticated');
});

The third route ('/authenticated') simply confirms that the user has been authenticated:

app.get('/authenticated', (req, res) => {
  res.send('You are authenticated now!');
});

Next, we define two "middleware" functions to handle requests that don't match any routes and to handle errors:

function notFound(req, res, next) {
  res.status(404);
  const error = new Error('Not Found - ' + req.originalUrl);
  next(error);
}
function errorHandler(err, req, res, next) {
  res.status(res.statusCode || 500);
  res.json({
    message: err.message,
    stack: err.stack
  });
}
app.use(notFound);
app.use(errorHandler);

These functions provide helpful error messages to users and developers.

Finally, we make our app listen on a specific port:

var interfaces = require('os').networkInterfaces(), localhostIP;
for (var k in interfaces) {
    for (var k2 in interfaces[k]) {
        let ipFamily = interfaces[k][k2].family;
       if ( ipFamily === 'IPv4' || ipFamily === 4 && !interfaces[k][k2].internal) {
          localhostIP = interfaces[k][k2].address;
       }
   }
}
const port = process.env.PORT || 5000;
app.listen(port, () => {
    console.log(`Listening on http://${localhostIP}:${port}`);
});

This script starts our app listening on the port specified by the environment variable PORT, or 5000 if PORT isn't defined. The server's address is logged to the console when the server starts.

And that's it! You've just learned how to set up a simple OAuth2 authentication flow with Google APIs and Express. It's not so difficult when you break it down, right? Happy coding!

Full code

const { google }          = require('googleapis');
const fs                  = require('fs');
const path                = require('path');
const CREDENTIALS_FOLDER  = './';
const SCOPES              = ['https://www.googleapis.com/auth/gmail.send'];

/* GLOBAL VARIABLES*/
let credentials;


// ----------  OAUTH2 CLIENT ----------------
// Load client secrets into "credentials"
try {
  const files = fs.readdirSync(CREDENTIALS_FOLDER);
  const credentialsFile = files
    .find(file => file.startsWith('client_secret_') && file.endsWith('.json'));

  if (!credentialsFile) throw new Error('credentials file not found');

  // const credentialsPath = CREDENTIALS_FOLDER + credentialsFile;
  const credentialsPath = path.join(__dirname, CREDENTIALS_FOLDER, credentialsFile);
  const file = fs.readFileSync(credentialsPath, 'utf8');
  credentials = JSON.parse(file);
} catch (error) {
  console.log("unable to read file, can't continue");
}

// VALIDATE CREDENTIALS 
const REQUIRED_CREDENTIALS_PROPERTIES = [
  'client_id',
  'project_id',
  'auth_uri',
  'auth_provider_x509_cert_url',
  'token_uri',
  'client_secret',
  'redirect_uris'
];

// Ensure all required properties exist
if (!credentials || !credentials.installed) {
  throw new Error('credentials or installed not found in credentials');
}

REQUIRED_CREDENTIALS_PROPERTIES.forEach(prop => {
  if (!(prop in credentials.installed)) 
    throw new Error(`Property ${prop} not found in credentials`);
});

const { installed: { client_id, client_secret, redirect_uris } } = credentials;
const oAuth2Client = new google.auth.OAuth2(client_id, client_secret, redirect_uris[0]);

let authUrl = oAuth2Client.generateAuthUrl({
  access_type: 'offline',
  scope: SCOPES
});

// ----------  EXPRESS APPLICATION  ----------------
const express = require('express');
const app     = express();

app.get('/', (req, res) => {
  res.send(`<a href="${authUrl}">Authorize</a>`);
});

app.get('/oauth2callback', async (req, res) => {
  const { code } = req.query;
    const { tokens } = await oAuth2Client.getToken(code);
    oAuth2Client.setCredentials(tokens);
    res.redirect('/authenticated');
});

app.get('/authenticated', (req, res) => {
  res.send('You are authenticated now!');
});
// ----------  EXPRESS FALLBACKS  ----------------
function notFound(req, res, next) {
  res.status(404);
  const error = new Error('Not Found - ' + req.originalUrl);
  next(error);
}
function errorHandler(err, req, res, next) {
  res.status(res.statusCode || 500);
  res.json({
    message: err.message,
    stack: err.stack
  });
}
app.use(notFound);
app.use(errorHandler);

// gets the localhost IP address
var interfaces = require('os').networkInterfaces(), localhostIP;
for (var k in interfaces) {
    for (var k2 in interfaces[k]) {
        let ipFamily = interfaces[k][k2].family;
       if ( ipFamily === 'IPv4' || ipFamily === 4 && !interfaces[k][k2].internal) {
          localhostIP = interfaces[k][k2].address;
       }
   }
}

const port = process.env.PORT || 5000;

app.listen(port, () => {
    console.log(`Listening on http://${localhostIP}:${port}`);
});

Explaining the video "Enums Considered Harmful" of Matt Pocock

Fredy Sandoval — Sun, 18 Dec 2022 04:16:14 +0000

I was watching this video by Matt Pocock, but I found really hard to digest and internalize the TypeScript, so I decided to create a little guide, because I learn better when I explain things to others, so here it is.
The TypeScript shown in the video

const LOG_LEVEL = {
   DEBUG: 'debug',
   WARNING: 'warning',
   ERROR: 'error',
} as const;

type ObjectValues<T> = T[keyof T];
type LogLevel = ObjectValues<typeof LOG_LEVEL>

Destructuring...

'typeof' will get you the types

type LOG_LEVEL_TYPE = typeof LOG_LEVEL;
// Hardcoded will be like this:
type LOG_LEVEL_TYPE_2 = {
    readonly DEBUG: "debug";
    readonly WARNING: "warning";
    readonly ERROR: "error";
}

'keyof' will get the keys

type LOG_LEVEL_KEYS = keyof LOG_LEVEL_TYPE;
// Hardcoded will be like this:
type LOG_LEVEL_KEYS_2 = "ERROR" | "WARNING" | "DEBUG"

'type[i]' will get the values

type LOG_LEVEL_VALUES = LOG_LEVEL_TYPE["ERROR" | "WARNING" | "DEBUG"];
// or
type LOG_LEVEL_VALUES_2 = LOG_LEVEL_TYPE[LOG_LEVEL_KEYS];
// Hardcoded will be like this:
type LOG_LEVEL_VALUES_3 = "debug" | "warning" | "error"

For example the variable myLog can only be the VALUES, anything else will throw an error

let myLog: LOG_LEVEL_VALUES;
myLog = 'debug';
myLog = 'warning';
myLog = 'error';

MyLog_2 can only be the KEYS

let myLog_2: LOG_LEVEL_KEYS;
myLog_2 = 'DEBUG';
myLog_2 = 'ERROR';
myLog_2 = 'WARNING';

The previous can also be compressed and written like this:

type LOG_LEVEL_VALUES_4 = typeof LOG_LEVEL[keyof typeof LOG_LEVEL];
// Hardcoded will be like this:
type LOG_LEVEL_VALUES_5 = "debug" | "warning" | "error"

Now explaining the TypeScript will be:

type ObjectValues<T> = T[keyof T];

// Imagine it as a function that returns the values of wherever T is.
function ObjectValues(T:any) {
    return T[Object.keys(T)[0]]
}

for example:

type MyType = {
   myString: 'my string',
   myNumber: 23,
}

let myValue:ObjectValues<MyType>;
myValue = 'my string' // can only be the litteral string,
myValue = 23;         // or the litteral value

Explaining the last part

type LogLevel = ObjectValues<typeof LOG_LEVEL>
// Now imagine this part like we actually execute the function and 
// we passed the types provided by "typeof"
let logLevel = ObjectValues({ myString: 'my string'})

Playground Link

TypeScript: A beginner's guide with emojis 🤗

Fredy Sandoval — Wed, 07 Dec 2022 22:02:32 +0000

Is basically telling what type something is.

For example let say we have a box,
and we want to tell people to only put eggs in the box.

let myBox; // 📦

In real life we would put a sticker in the box saying "only eggs
please 📄", in TypeScript we do the same, we add a "type" saying what something is and only accepts.

  Variable           Type            value
┌────┴─────┐     ┌────┴─────┐      ┌───┴───┐
let myBox_📦  :  onlyEggs_📄   =   "🥚🥚🥚";
               ↑                ↑
               Separator        Assignment operator

There are 3 basic types in TypeScript

let isDone: boolean = false;              // 😀 or 😟

let lines: number   = 42;                 // 0️⃣1️⃣2️⃣3️⃣4️⃣5️⃣...

let name: string    = "John";             // 📃

When it's impossible to know, there is the "Any" type

let notSure: any = 4;                     // 🤷‍♂️ Not sure

notSure = "I'm a string";                 // I can change it later

notSure = false;                         // maybe a boolean

There are typed arrays

let list: number[] = [1, 2, 3];

// or with emojis:
        Only chickens please!
              ┌─┴─┐ 
let chickens: 🐔[] = [🐣,🐤,🐥,🐓];

Alternatively you can use Array which It's same as Type[]

let list: Array<number> = [1, 2, 3];

// or with emojis
let listOfChickens: Array<🐔> = [🐣,🐤,🐥,🐓];

Enumerations also known as enums:

enum Square { Red, Green, Blue };         // 🟥, 🟩, 🟦

// This can be understood better by seeing what Enumerations 
// are compiled to in JavaScript:
Square = { 
           0       :   'Red', 
           1       :   'Green', 
           2       :   'Blue', 
           Red     :    0, 
           Green   :    1, 
           Blue    :    2,
          };

// Now that you know is just an object, 
// you can access it by name or number.
console.log( Square.Green );              //  🟩
console.log( Square[2] );                 //  🟥 

// or in a more complex way
let c: Square = Square.Blue;
console.log( Square[c] );                 //  🟦

Please Comment if you want to see more content like this!
👇 Follow me on Twitter

DEV Community: Fredy Sandoval

Lessons from Astro Starlight: Designing a Maintainable i18next Architecture

1. Separate locale resolution from translation lookup

General lesson

2. Treat translation dictionaries as application data

Why this matters

Recommended pattern

3. Use different validation strictness for canonical and override catalogs

Canonical/default locale

Secondary locales

4. Establish an explicit translation precedence

5. Give extensions a translation registration API

6. Hide the raw i18next instance behind an application API

General lesson

7. Bind translators to the request or rendering context

8. Make fallback behavior part of the product policy

9. Use proper locale identifiers

10. Make RTL direction part of the i18n service

11. Keep translation keys stable and semantic

12. Use interpolation for dynamic values, not sentence construction

13. Integrate third-party UI into the same translation pipeline

14. Make translation keys part of the TypeScript API

15. File structure: what to copy and what to adapt

16. A generalized architecture

17. Recommended React implementation

18. Suggested translation pipeline

19. Tests worth adding

20. What specifically should be copied from Starlight?

21. What should not be copied literally?

One namespace

Eagerly assembled resources

Astro content collections

Astro middleware

Flat dotted keys

22. Recommended baseline for a new project

Conclusion

Bare-Metal Convex: Develop and Deploy with the Minimum Stack Possible

What this setup is

1. Download the correct Convex backend binary

2. Directory model

Development setup

3. Create the first instance

4. Create start.sh

About --disable-beacon

5. The UDF fetch requests are unrestricted warning

Admin keys

6. Generate the Convex admin key

Build the helper once

Connect application code

7. Point a Convex project at the local backend

Warnings we encountered

Node localStorage experimental warning

/tmp and project are on different filesystems

Filesystem changed during push, retrying...

8. Development process model

Multiple independent apps on one machine

9. Create app2

10. Verify processes

Security lesson: ps can expose the instance secret

Dashboard

11. The dashboard is optional

Production deployment

12. Replace convex dev with a one-time deploy

13. Build the frontend separately

Production networking: Tailscale + Cloudflare Tunnel

14. Why no Nginx or Caddy is required

15. Use two public Convex hostnames

16. Cloudflare Tunnel routing

17. Production application environment

Tailscale and firewall

18. Use Tailscale for administration

19. UFW model for the VM

systemd production service

20. Keep Convex running without a terminal

Resource usage findings

21. What we observed

Important production notes

22. SQLite is the minimum, not necessarily the final database architecture

23. Do not confuse three different kinds of environment variables

Backend process configuration

4. Create `start.sh`

About `--disable-beacon`

5. The `UDF fetch requests are unrestricted` warning

`/tmp` and project are on different filesystems

`Filesystem changed during push, retrying...`

9. Create `app2`

Security lesson: `ps` can expose the instance secret

12. Replace `convex dev` with a one-time deploy

Mistake: leaving `npx convex dev` running in production

Mistake: regenerating `INSTANCE_SECRET` every boot

Mistake: exposing secrets with `ps`

Mistake: assuming `/version` must display a release number

Mistake: thinking Cloudflare Tunnel restricts Convex `fetch()`

`node --version` shows the wrong version

`just: command not found`