No native modules, iOS pods, or Android linking steps are required. Zipline requires a CPU with AVX support for image processing; verify before deploying on ARM or older hardware.

Project setup

1. Copy source: Place the contents of source/ into your project root, or clone alongside your existing repo and reference it as a workspace package via pnpm-workspace.yaml.

2. PostgreSQL: Provision a PostgreSQL 16 instance. Set the connection string:

   DATABASE_URL=postgres://zipline:password@localhost:5432/zipline
   

3. Required environment variables:

   CORE_SECRET=your-random-32-char-secret   # mandatory; server will not start without it
   CORE_PORT=3000
   CORE_HOSTNAME=0.0.0.0
   DATABASE_URL=postgres://user:pass@host:5432/db
   DATASOURCE_TYPE=local                    # or "s3"
   DATASOURCE_LOCAL_DIRECTORY=./uploads
   

4. Run migrations:

   npx prisma migrate deploy
   

5. Build:

   pnpm install
   pnpm build       # builds both server (tsup) and client (vite)
   

6. Start:

   node dist/server/index.js
   

7. tsconfig paths: The source uses @/ as a path alias pointing to src/. Add to your tsconfig.json:

   {
     "compilerOptions": {
       "paths": {
         "@/*": ["./src/*"]
       }
     }
   }
   

   Mirror this alias in vite.config.ts under resolve.alias.

Public API

step

function step(
  name: string,
  command: string | (() => void | Promise<void>),
  condition?: () => boolean
): { name: string; command: StepCommand; condition: () => boolean }

Creates a named build step with an optional run condition. Pass a shell command string or an async function. Used as input to run(). The condition defaults to () => true; supply a function returning false to skip the step dynamically (e.g., based on environment or file existence).

run

async function run(name: string, ...steps: Step[]): Promise<void>

Executes an ordered sequence of Step objects under a named pipeline. Respects process.argv[2] to run a single named step in the format "pipelineName/stepName". Each step is logged, timed, and on failure the process exits with code 1. Use this to compose build, migration, or deployment pipelines in scripts/.

loader (folder page)

async function loader({
  params,
  request,
}: {
  params: Params<string>;
  request: Request;
}): Promise<{ initial: Response['/api/server/folder/[id]'] }>

React Router data loader for the public folder view. Fetches paginated folder contents from /api/server/folder/:id. Throws a Response with status 404 if the folder does not exist. Wire this to the <Route loader={loader} /> for the /folder/:id path.

Working examples

Scenario - Running a custom build pipeline

Use step and run from scripts/index.ts to orchestrate Prisma migration followed by a server build in a single script.

// scripts/deploy.ts
import { step, run } from './index';
import { existsSync } from 'fs';

await run(
  'deploy',
  step('migrate', 'npx prisma migrate deploy'),
  step('build-server', 'npx tsup src/server/index.ts --format cjs --outDir dist/server'),
  step(
    'build-client',
    'npx vite build',
    () => existsSync('vite.config.ts')
  ),
);

Run a single step: tsx scripts/deploy.ts deploy/migrate

Scenario - Wiring the folder page loader in React Router

Attach Zipline's folder loader to your React Router v6 route tree so that folder data is fetched server-side before rendering.

// src/router.tsx
import { createBrowserRouter } from 'react-router-dom';
import { loader as folderLoader } from '@/client/pages/folder/[id]/index';

const FolderPage = () => import('@/client/pages/folder/[id]/index');

export const router = createBrowserRouter([
  {
    path: '/folder/:id',
    lazy: FolderPage,
    loader: folderLoader,
  },
]);

The loader automatically reads page and perpage from the URL query string and returns { initial } which the component consumes via useLoaderData().

Scenario - Embedding DashboardFile in a custom gallery view

Render Zipline's file card component inside your own grid layout, intercepting the open event instead of using the built-in modal.

// src/components/MyGallery.tsx
import { lazy, Suspense } from 'react';
import { SimpleGrid, Skeleton } from '@mantine/core';
import type { File } from '@/lib/db/models/file';

const DashboardFile = lazy(() => import('@/components/file/DashboardFile'));

export function MyGallery({ files }: { files: File[] }) {
  function handleOpen(fileId: string) {
    // custom side-panel logic
    console.log('Open file', fileId);
  }

  return (
    <SimpleGrid cols={4}>
      {files.map((file) => (
        <Suspense key={file.id} fallback={<Skeleton height={180} radius='md' />}>
          <DashboardFile
            file={file}
            reduce={false}
            id={file.id}
            onOpen={handleOpen}
          />
        </Suspense>
      ))}
    </SimpleGrid>
  );
}

When onOpen is provided, DashboardFile suppresses its internal modal and delegates open handling to the parent.

File walkthrough

• .github/ - GitHub Actions workflows: Docker image publish, OpenAPI spec generation, and PR/push builds.
• docker/ - entrypoint.sh initializes the container environment; ziplinectl.sh is a CLI wrapper for container management tasks.
• prisma/ - schema.prisma defines all database models (User, File, Folder, URL, Session, etc.); migrations/ contains ordered SQL migration files applied via prisma migrate deploy.
• public/ - Static files (logos, favicons) served directly by Fastify's static plugin at the root path.
• scripts/ - Build orchestration: exports step and run used by build and deploy scripts.
• src/ - Monolithic source tree split into client/ (React pages and components), server/ (Fastify routes and plugins), and lib/ (shared utilities, DB models, API response types).
• mimes.json - MIME-to-extension mapping consumed by the upload handler for file type detection.
• tsup.config.ts - Configures tsup to bundle the Fastify server into dist/.
• vite.config.ts - Configures Vite to build the React client with @/ path aliases and CSS modules.
• postcss.config.cjs - PostCSS config required by Mantine for CSS variable generation.

Common pitfalls and fixes

• Missing CORE_SECRET: The server refuses to start without this variable. Generate one with openssl rand -base64 42 | tr -dc A-Za-z0-9 | cut -c -32.
• AVX CPU requirement: Zipline's image processing (sharp/ffmpeg) requires AVX instructions. On non-AVX VMs or older ARM hosts, the process will crash. Verify with grep avx /proc/cpuinfo.
• Prisma client out of sync: After pulling new migrations, always run npx prisma generate before building, otherwise the generated client will not match the schema.
• @/ path alias not resolved: Both tsconfig.json and vite.config.ts must declare the alias. Forgetting one causes client build to succeed but IDE or server build to fail.
• pnpm workspace isolation: If you add Zipline source into a pnpm monorepo, ensure pnpm-workspace.yaml includes the correct package glob; otherwise shared deps are duplicated.
• Mantine version mismatch: All @mantine/* packages must be the same version. Mixing versions (e.g., @mantine/core@7 with @mantine/hooks@6) causes silent hook failures at runtime.

Vibe-coding prompt template

I have dropped the Zipline source (zipline@4.5.3) into the `source/` directory
of my project. I also have `source/USAGE.md` open for reference.

Please help me integrate Zipline into my existing Node.js/TypeScript project
step by step:

1. Read `source/USAGE.md` for the full dependency list and setup steps.
2. Install all required npm dependencies listed in the "Required dependencies"
   section of USAGE.md into my project's package.json.
3. Set up the `tsconfig.json` and `vite.config.ts` path alias `@/` → `src/`.
4. Wire the Prisma schema from `source/prisma/schema.prisma` and run migrations
   against my DATABASE_URL.
5. Integrate the Fastify server entry point from `source/src/server/` into my
   existing server, or run it standalone on a separate port.
6. Add the React Router routes for the dashboard and folder pages from
   `source/src/client/pages/` into my client router.
7. Show me how to embed the `DashboardFile` component from
   `source/src/components/file/DashboardFile/index.tsx` in my own gallery page.
8. Point out any environment variables I must set before first run, based on
   `source/USAGE.md` and `source/README.md`.

Use real imports from the source files. Do not invent APIs.

License and credit

Zipline is released under the license found in source/LICENSE. See the upstream repository and documentation at zipline.diced.sh and the npm package user@example.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.