Zero-com

The 0 bytes utility for transparently communicating client and server in full-stack projects through compile-time code transformation, with end-to-end static type checking.

Table of Contents

• Usage
• Transport layer
• Context
• Server-to-Server Calls
• Plugin options
• Complete Example

Usage

Zero-com can be used with either Webpack or Rollup.

Webpack

To use Zero-com with Webpack, you need to add the ZeroComWebpackPlugin to your webpack.config.js file.

// webpack.config.js
const { ZeroComWebpackPlugin } = require('zero-com/webpack');

module.exports = {
  // ... your webpack config
  plugins: [
    new ZeroComWebpackPlugin({
      development: true,
    }),
  ],
};

Rollup

To use Zero-com with Rollup, you need to add the zeroComRollupPlugin to your rollup.config.js file.

// rollup.config.js
import zeroComRollupPlugin from 'zero-com/rollup';

export default {
  // ... your rollup config
  plugins: [
    zeroComRollupPlugin({
      development: true,
    }),
  ],
};

The above code will identify all the references from client-side code to the server-side files and will tranform the modules to comunicate through your defined transport layer. The only callable functions in the server-side modules will be the exported async functions. See the example below.

Server side

// server/phones.ts
import { func } from 'zero-com';

export const getPhones = func(async () => {
  // ...
})

Client side

// client/phones.tsx
import { getPhones } '../server/phones'

Transport layer

Zero-com does not define any transport layer, it is up to you to create one or reuse your own. This means you have complete control over how data is sent between the client and server.

Client-side

All messages from the client-side will be sent using the transport function you define. Import call from zero-com and pass your transport function.

// client/transport.js
import { call } from 'zero-com';

call(async (funcId, params) => {
  const response = await fetch('http://localhost:8000/api', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ funcId, params }),
  });
  return await response.json();
});

Server-side

On the server-side, you need to create a handler that receives messages from the client, executes the corresponding function, and returns the result. Import handle from zero-com and call it with the function ID, context, and arguments.

// server/api.js
import { handle } from 'zero-com';

const someCustomHandler = async (message, ctx) => {
  return await handle(message.funcId, ctx, message.params);
};

// Example of how to use the handler with an Express server
import express from 'express';

const app = express();
app.use(express.json());

app.post('/api', async (req, res) => {
  try {
    const ctx = { req, res };
    const result = await someCustomHandler(req.body, ctx);
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(8000, () => {
  console.log('Server running at http://localhost:8000/');
});

Context

Often you want to access context-related data in your server functions, such as the request, response, session, etc. Zero-com provides a simple way to do this using the context() function.

Accessing Context in Server Functions

To access context in a server function, call the context<T>() function inside your function body. The context is automatically available when the function is called via handle().

// server/api/phones.ts
import { func, context } from 'zero-com';

type MyContext = {
  req: any;
  res: any;
  userId: string;
}

export const getPhones = func(async (name: string) => {
  // Get the context inside the function
  const ctx = context<MyContext>();

  console.log('User:', ctx.userId);
  console.log('Headers:', ctx.req.headers);

  // ... your code
});

Providing Context on the Server

Pass the context as the second argument to handle(). The context will be available to the function and any nested server function calls.

// server/api.js
import { handle } from 'zero-com';

app.post('/api', async (req, res) => {
  const { funcId, params } = req.body;

  // Create context with request data
  const ctx = {
    req,
    res,
    userId: req.headers['x-user-id']
  };

  // Pass context to handle - it will be available via context()
  const result = await handle(funcId, ctx, params);
  res.json(result);
});

Server-to-Server Calls

When one server function calls another server function, the call bypasses the transport layer and executes directly. Context is automatically propagated to nested calls.

// server/api/user.ts
import { func, context } from 'zero-com';

export const getFirstName = func(async () => {
  const ctx = context<{ userId: string }>();
  // ... fetch first name from database
  return 'John';
});

// server/api/profile.ts
import { func, context } from 'zero-com';
import { getFirstName } from './user';

export const getFullName = func(async (lastName: string) => {
  // This calls getFirstName directly (no transport layer)
  // Context is automatically propagated
  const firstName = await getFirstName();
  return `${firstName} ${lastName}`;
});

When getFullName is called from the client:

1. The call goes through the transport layer to the server
2. handle() sets up the context
3. getFullName executes and calls getFirstName
4. getFirstName executes directly (no transport) with the same context
5. Both functions can access context() with the same data

Calling server functions outside handle()

Server functions can be called from any server-side code, not only through the RPC path. This is useful for server-side-only integrations like authentication callbacks, cron jobs, or webhook handlers.

// pages/api/auth/[...nextauth].ts  (Next.js example)
import { getUserByCredentials } from '../../../server/auth/funcs'

const user = await getUserByCredentials(email, password)

When called outside handle(), the function executes directly with no context. If the function calls context() internally, it throws:

Error: context() called outside of a server function

Use runWithContext to provide a context in those cases:

import { runWithContext } from 'zero-com'

const authorize = async (credentials) => {
  return runWithContext({}, async () => {
    const user = await getUserByCredentials(credentials.email, credentials.password)
    return user ?? null
  })
}

runWithContext accepts any object as the context value, which will be returned by context() inside any server function called within the callback.

When called inside handle(), context is propagated automatically to the function and any nested func() calls, same as the normal RPC path.

File boundary rule

Any file that contains func() exports is treated as a server-only module. On the client build the plugin replaces the entire file with lightweight RPC stubs — only the func() exports survive, everything else in that file is discarded.

This means you must not mix func() declarations with client-side code (state, UI utilities, etc.) in the same file. The pattern is the same as Next.js "use server" files: one side of the boundary per file.

Wrong — connect will be undefined on the client because the whole file is replaced:

// store.ts  ❌
import { func } from 'zero-com'
import { createStore } from './create-store'

export const { connect, useStore } = createStore(...)  // lost on client

export const getPhones = func(async () => { ... })

Right — separate the RPC calls from client state:

// funcs.ts  ✅  (replaced with stubs on client)
import { func } from 'zero-com'
export const getPhones = func(async () => { ... })

// store.ts  ✅  (untouched on client)
import { createStore } from './create-store'
export const { connect, useStore } = createStore(...)
export * from './funcs'

Plugin options

| Option | Type | Description | |-------------|-----------|-----------------------------------------------------------------------------| | development | boolean | If false, will add internal variable renaming to the final bundle. | | target | 'client' \| 'server' | When 'client', server function files are replaced with lightweight RPC stubs containing no server dependencies. When 'server', full function bodies and registry code are preserved. When omitted, the Vite/Rollup plugin infers it from the ssr flag in the transform hook. |

Complete Example

Here's a complete example of how to use Zero-com in a project.

Project Structure

.
├── package.json
├── webpack.config.js
├── rollup.config.js
└── src
    ├── client
    │   ├── index.ts
    │   └── transport.ts
    └── server
        └── api
            └── phones.ts

Client-side

// src/client/index.ts
import { getPhones } from '../../server/api/phones';

async function main() {
  const phones = await getPhones('iPhone');
  console.log(phones);
}

main();

// src/client/transport.ts
import { call } from 'zero-com';

call(async (funcId, params) => {
  const response = await fetch('http://localhost:8000/api', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ funcId, params }),
  });
  return await response.json();
});

Server-side

// src/server/api/phones.ts
import { func, context } from 'zero-com';

type Context = {
  req: any;
  res: any;
}

export const getPhones = func(async (name: string) => {
  // Access context when needed
  const ctx = context<Context>();
  console.log('Request from:', ctx.req.ip);

  // In a real application, you would fetch this from a database
  const allPhones = [
    { name: 'iPhone 13', brand: 'Apple' },
    { name: 'Galaxy S22', brand: 'Samsung' },
  ];

  return allPhones.filter((phone) => phone.name.includes(name));
});

Server

// server.ts
import express from 'express';
import { handle } from 'zero-com';
// No manual imports needed — the plugin automatically registers all func() files
// when it transforms any file that calls handle()

const app = express();
app.use(express.json());

app.post('/api', async (req, res) => {
  const { funcId, params } = req.body;
  try {
    const result = await handle(funcId, { req, res }, params);
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(8000, () => {
  console.log('Server running at http://localhost:8000/');
});

Webpack Configuration

// webpack.config.js
const { ZeroComWebpackPlugin } = require('zero-com/webpack');

module.exports = {
  mode: 'development',
  entry: './src/client/index.js',
  output: {
    filename: 'main.js',
    path: __dirname + '/dist',
  },
  plugins: [
    new ZeroComWebpackPlugin(),
  ],
};

Rollup Configuration

// rollup.config.js
import zeroComRollupPlugin from 'zero-com/rollup';

export default {
  input: 'src/client/index.js',
  output: {
    file: 'dist/main.js',
    format: 'cjs',
  },
  plugins: [
    zeroComRollupPlugin(),
  ],
};