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.

Hướng dẫn cài đặt đầy đủ và prompt tích hợp sẽ mở khóa sau khi mua.