vercel-labs / vercel-labs/native

feat(packaging): support manifest-declared bundled helper executables

Open
#167 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Zig
Stars
7.7k
Forks
314
Avg merge
5h
Merged PRs (30d)
13

Description

Problem

Desktop apps often need to ship a helper process, such as a Node server, language server, media processor, or Python runtime.

Native can launch child processes, but native package has no first-class knowledge of them. Apps must currently rely on PATH or manually copy files into the bundle, resolve installation paths, preserve executable permissions, and handle nested code signing themselves.

Proposed initial scope

A macOS-first implementation would already be useful:

  • Declare a helper executable in app.zon using a stable logical ID.
  • Copy it into an SDK-owned location inside the packaged .app.
  • Preserve its executable permission.
  • Provide an API to resolve its installed path by ID.
  • Fail packaging if the helper is missing or built for the wrong architecture.
  • Sign the helper before signing the outer app bundle.
  • Include it in notarization and package verification.

Illustrative API only:

.helpers = .{
    .{ .id = "app-server", .path = "dist/app-server" },
};

const path = try runtime.helperPath("app-server");

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the native package flow and the app.zon manifest, then trace how runtime APIs could resolve an installed helper by its logical ID. Treat the macOS-first scope as complete when packaging copies and validates helpers, preserves permissions, signs them before the app, and includes them in notarization and verification.

Written by the indexing model from the issue text.

Assessment

Tech stack
macos, zig
Domain
build-system, desktop
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.