{"id":49385,"library":"socio","title":"Socio","description":"A WebSocket Real-Time Communication (RTC) API framework for building reactive front-end and back-end applications. Current stable version 1.15.16, released regularly. Key differentiator: allows writing SQL in frontend code that automatically syncs across all clients upon data changes; also provides real-time server props for generic data synchronization. Agnostic of framework, build tool, server library, and SQL database. Requires Node.js >= 16 LTS. Ships TypeScript definitions.","status":"active","version":"1.15.16","language":"javascript","source_language":"en","source_url":"https://github.com/Rolands-Laucis/Socio","tags":["javascript","websocket","rtc","api","framework","reactive","database","sync","live","typescript"],"install":[{"cmd":"npm install socio","lang":"bash","label":"npm"},{"cmd":"yarn add socio","lang":"bash","label":"yarn"},{"cmd":"pnpm add socio","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"SocioServer is not exported from the main entry; must import from 'socio/dist/core-server'.","wrong":"import { SocioServer } from 'socio'","symbol":"SocioServer","correct":"import { SocioServer } from 'socio/dist/core-server'"},{"note":"ESM-only package; CommonJS require may fail or require .mjs extension. Client-side import from 'socio/dist/core-client'.","wrong":"const SocioClient = require('socio/dist/core-client')","symbol":"SocioClient","correct":"import { SocioClient } from 'socio/dist/core-client'"},{"note":"SocioSecurity is in 'socio/dist/secure' module, not main export. Used for encrypting SQL queries.","wrong":"import { SocioSecurity } from 'socio'","symbol":"SocioSecurity","correct":"import { SocioSecurity } from 'socio/dist/secure'"},{"note":"Type for the session object in QueryWrap callback; exported from core-server.","wrong":"import { SocioSession } from 'socio'","symbol":"SocioSession","correct":"import { SocioSession } from 'socio/dist/core-server'"}],"quickstart":{"code":"import { SocioServer } from 'socio/dist/core-server';\nimport { SocioSecurity } from 'socio/dist/secure';\nimport { SocioClient } from 'socio/dist/core-client';\n\n// Server (Node.js)\nconst socsec = new SocioSecurity({ secure_private_key: 'my-secret-key', logging: { verbose: false } });\nconst socserv = new SocioServer({ port: 3000 }, {\n  db: {\n    Query: async (client, id, sql, params) => {\n      // Simulate database query; replace with actual DB call\n      return [{ id: 1, name: 'Alice' }];\n    }\n  },\n  socio_security: socsec,\n  logging: { verbose: false }\n});\n\n// Client (browser)\nconst client = new SocioClient('ws://localhost:3000');\nawait client.Connect();\nconst result = await client.Query('SELECT * FROM users WHERE id = ?', [1]);\nconsole.log(result);\nclient.Disconnect();","lang":"typescript","description":"Sets up a Socio server and client, establishes WebSocket connection, executes a parameterized SQL query."},"warnings":[{"fix":"Use correct subpath imports: for server 'socio/dist/core-server', for client 'socio/dist/core-client', for security 'socio/dist/secure'.","message":"Import paths differ for server vs client: 'socio/dist/core-server' vs 'socio/dist/core-client'.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the same 'secure_private_key' is used in both server-side SocioSecurity instance and the Vite plugin during build.","message":"SQL queries in frontend code are encrypted with AES-256-GCM; the encryption key must match between SocioSecurity and SocioSecurityVitePlugin.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always await .Connect() before calling query/subscribe methods. Handle connection errors with try-catch.","message":"SocioClient methods like .Query() and .Subscribe() are async and may throw if connection is not established.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use dynamic import() or configure your project to use ESM. Avoid CommonJS require.","message":"Require() calls may not work in ESM-only environments; package is ESM-only since version 1.x.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Ensure QueryWrap is async and returns the expected data structure (e.g., array of rows).","message":"The QueryWrap function on server must return a promise that resolves to an array or object; otherwise undefined behavior.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.15.16':25 '16':68 'across':39 'agnost':56 'allow':30 'also':45 'api':9,76 'applic':21 'automat':37 'back':19 'back-end':18 'build':12,59 'chang':44 'client':41 'code':35 'communic':7 'current':22 'data':43,54 'databas':65,79 'definit':72 'differenti':29 'end':16,20 'framework':10,58,77 'front':15 'front-end':14 'frontend':34 'generic':53 'javascript':73 'key':28 'librari':62 'live':81 'lts':69 'node.js':67 'prop':51 'provid':46 'reactiv':13,78 'real':5,48 'real-tim':4,47 'regular':27 'releas':26 'requir':66 'rtc':8,75 'server':50,61 'ship':70 'socio':1 'sql':32,64 'stabl':23 'sync':38,80 'synchron':55 'time':6,49 'tool':60 'typescript':71,82 'upon':42 'version':24 'websocket':3,74 'write':31","created_at":"2026-06-07T17:01:30.717213+00:00","updated_at":"2026-06-07T17:01:30.717213+00:00","problems":[{"fix":"Add \"type\": \"module\" to your package.json or use .mjs extension for import files.","cause":"Trying to use ESM imports in a CommonJS project or without type:'module' in package.json.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Use correct import: import { SocioClient } from 'socio/dist/core-client';","cause":"Importing from wrong path (e.g., 'socio' instead of 'socio/dist/core-client').","error":"TypeError: socio_core_1.SocioClient is not a constructor"},{"fix":"Use ESM import/export exclusively. Remove module.exports and use export default / export.","cause":"Mixing CommonJS module.exports with ESM imports in the same file.","error":"ReferenceError: exports is not defined in ES module scope"},{"fix":"Switch to dynamic import() or convert your project to ESM. Use import syntax.","cause":"Using require() to load Socio which is an ESM-only package.","error":"ERR_REQUIRE_ESM: require() of ES Module not supported"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/Rolands-Laucis/Socio#readme","github":"https://github.com/Rolands-Laucis/Socio","docs":null,"changelog":null,"pypi":null,"npm":"socio","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}