{"id":17961,"library":"streamby-core","title":"StreamBy Core Middleware","description":"@streamby/core is a robust, plug-and-play middleware framework designed for integrating storage-agnostic media management capabilities into existing Express.js (or compatible) applications. Currently at version `0.26.10`, the package provides functionality for file uploads, listings, and multi-project access across various storage providers like AWS S3, with planned support for Google Cloud Storage, Cloudflare R2, and local servers. It aims for a rapid, minor version release cadence, indicating active development and feature enhancements. A key differentiator is its architectural approach: it operates as a library within your existing API, eliminating the need to deploy and manage a separate backend service for media handling. This design promotes tight integration and simplifies deployment, offering a flexible solution for developers building scalable media-centric applications who require fine-grained control over their backend stack and data.","status":"active","version":"0.26.10","language":"javascript","source_language":"en","source_url":"https://github.com/GwerhDev/StreamBy-Package","tags":["javascript","streamby","middleware","upload","storage","s3","express","typescript"],"install":[{"cmd":"npm install streamby-core","lang":"bash","label":"npm"},{"cmd":"yarn add streamby-core","lang":"bash","label":"yarn"},{"cmd":"pnpm add streamby-core","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency as `@streamby/core` is an Express middleware framework.","package":"express","optional":false},{"reason":"Runtime dependency for WebSocket server functionality required for real-time operations.","package":"ws","optional":false}],"imports":[{"note":"The package is primarily designed for ESM/TypeScript environments. While CommonJS `require` might work with transpilation, direct ESM imports are preferred.","wrong":"const { createStreamByRouter } = require('@streamby/core');","symbol":"createStreamByRouter","correct":"import { createStreamByRouter } from '@streamby/core';"},{"note":"This is a subpath import for PostgreSQL-specific database schema setup. Ensure the full path is used.","wrong":"import { setupStreambyPg } from '@streamby/core';","symbol":"setupStreambyPg","correct":"import { setupStreambyPg } from '@streamby/core/pg/setup';"},{"note":"This is a subpath import for MongoDB-specific database schema setup. Ensure the full path is used.","wrong":"import { setupStreambyMongo } from '@streamby/core';","symbol":"setupStreambyMongo","correct":"import { setupStreambyMongo } from '@streamby/core/mongo/setup';"}],"quickstart":{"code":"import http from 'http';\nimport express from 'express';\nimport { WebSocketServer } from 'ws';\nimport { createStreamByRouter } from '@streamby/core';\n\nconst app = express();\nconst server = http.createServer(app);\nconst wss = new WebSocketServer({ server, path: '/streamby/ws' });\n\napp.use('/streamby', express.json(), createStreamByRouter({\n  authProvider: async (req) => {\n    // In a real application, validate token/session and return user info\n    return { userId: 'user-id-123', username: 'demo-user', role: 'admin' };\n  },\n  databases: [\n    { id: 'mongo', type: 'nosql', connectionString: process.env.MONGO_URI ?? 'mongodb://localhost:27017/streamby_test' },\n    { id: 'postgres', type: 'sql', connectionString: process.env.POSTGRES_URI ?? 'postgresql://user:password@localhost:5432/streamby_test', main: true }\n  ],\n  storageProviders: [\n    {\n      type: 's3',\n      config: {\n        bucket: process.env.AWS_BUCKET ?? 'your-s3-bucket-name',\n        region: process.env.AWS_REGION ?? 'us-east-1',\n        accessKeyId: process.env.AWS_ACCESS_KEY ?? 'YOUR_AWS_ACCESS_KEY_ID',\n        secretAccessKey: process.env.AWS_SECRET_KEY ?? 'YOUR_AWS_SECRET_ACCESS_KEY'\n      }\n    }\n  ],\n  encrypt: process.env.STREAMBY_ENCRYPTION_KEY ?? 'a_32_character_encryption_key_for_streamby',\n  websocket: { server: wss }\n}));\n\nserver.listen(3000, () => {\n  console.log('StreamBy Core example server listening on port 3000');\n});","lang":"typescript","description":"Demonstrates setting up an Express server with StreamBy core middleware, integrating an S3 storage provider, dummy authentication, and a WebSocket server for real-time capabilities. Requires `ws` and `@types/ws`."},"warnings":[{"fix":"Wrap your Express `app` instance with `http.createServer(app)` and pass the resulting `server` object to both `server.listen()` and the `WebSocketServer({ server })` constructor.","message":"When integrating `@streamby/core` with WebSocket functionality, it is crucial to use `http.createServer(app)` instead of `app.listen()` for the Express application. This ensures the `WebSocketServer` can share the same underlying HTTP server and port, preventing conflicts or connection failures.","severity":"gotcha","affected_versions":">=0.25.0"},{"fix":"At application startup, before any StreamBy operations, explicitly call the appropriate setup function: `setupStreambyPg({ pool, schema: 'streamby' })` for PostgreSQL or `setupStreambyMongo({ client, dbName: 'streamby' })` for MongoDB.","message":"StreamBy Core requires a pre-configured database schema (tables/collections and indexes) for its internal operations. It does not manage database connections or schema creation directly. Failing to initialize the schema will result in runtime errors when StreamBy Core attempts to access its data.","severity":"gotcha","affected_versions":">=0.25.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure `http.createServer(app)` is used to create the server, and this `server` object is passed to both `server.listen()` and the `WebSocketServer({ server })` constructor.","cause":"The WebSocket server is not correctly bound to or sharing the HTTP server instance.","error":"WebSocket connection failed"},{"fix":"Run the appropriate database schema setup function (`setupStreambyPg` for PostgreSQL or `setupStreambyMongo` for MongoDB) at your application's initialization phase, providing a connected database client/pool.","cause":"The necessary database schema for StreamBy Core has not been initialized or is inaccessible.","error":"Error: relation 'streamby.files' does not exist"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}