{"id":16571,"library":"velocious","title":"Velocious Full-Stack Framework","description":"Velocious is a comprehensive full-stack JavaScript/TypeScript framework providing a concurrent multi-threaded web server, a database framework with MVC concepts, and shared database models for both frontend and backend development. It includes features like database migrations, declarative state machines for models, and Rails-style nested-attribute writes. The current stable version is 1.0.336, suggesting a fairly active development cycle with frequent updates. Key differentiators include its unified model approach across frontend and backend, advanced testing capabilities like parallel test splitting and browser system tests, and integrated tooling for configuration and project initialization. It aims to provide a robust environment for building modern web applications with a focus on developer experience and performance.","status":"active","version":"1.0.336","language":"javascript","source_language":"en","source_url":"https://github.com/kaspernj/velocious","tags":["javascript","typescript"],"install":[{"cmd":"npm install velocious","lang":"bash","label":"npm"},{"cmd":"yarn add velocious","lang":"bash","label":"yarn"},{"cmd":"pnpm add velocious","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency likely used for email-related functionalities within the framework, such as sending notifications or transactional emails.","package":"smtp-connection","optional":false}],"imports":[{"note":"Configuration for testing needs to be imported from a specific internal path, not directly from the main package export. The `configureTests` function is used for global test settings like excluding tags.","wrong":"import { configureTests } from 'velocious'","symbol":"configureTesting","correct":"import { configureTests } from 'velocious/build/src/testing/test.js'"},{"note":"Event emitter for test lifecycle hooks (e.g., retries) is also found at the internal testing module path. This allows for custom actions during test execution.","wrong":"import { testEvents } from 'velocious'","symbol":"testEvents","correct":"import { testEvents } from 'velocious/build/src/testing/test.js'"},{"note":"Application configuration is typically managed by a default export from a `src/config/configuration.js` file, which needs to be explicitly set as the current configuration using `configuration.setCurrent()`.","wrong":"import { configuration } from 'velocious'","symbol":"configuration","correct":"import configuration from 'src/config/configuration.js'"}],"quickstart":{"code":"import { configureTests } from 'velocious/build/src/testing/test.js';\nimport { testEvents } from 'velocious/build/src/testing/test.js';\n\n// Initialize a new Velocious project\n// This creates basic project structure and config files.\n// npx velocious init\n\n// Example test configuration\nexport default async function configureTesting() {\n  configureTests({ excludeTags: [\"mssql\"] });\n}\n\n// Example of test suite setup with tagging and retries\ndescribe(\"User Management\", {tags: [\"api\", \"db\"]}, () => {\n  beforeAll(async () => {\n    // Setup database or other services before all tests in this suite\n    console.log(\"Setting up user management suite...\");\n  });\n\n  it(\"creates a new user successfully\", {tags: [\"fast\", \"write\"]}, async () => {\n    // Simulate user creation logic\n    await new Promise(resolve => setTimeout(resolve, 50));\n    expect(true).toBe(true);\n  });\n\n  it(\"handles duplicate username registration\", {retry: 1}, async () => {\n    // Simulate error handling for duplicates\n    await new Promise(resolve => setTimeout(resolve, 30));\n    expect(false).toBe(false);\n  });\n\n  afterAll(async () => {\n    // Teardown services after all tests\n    console.log(\"Tearing down user management suite.\");\n  });\n});\n\n// Listen for test retry events\ntestEvents.on(\"testRetrying\", ({ testDescription, nextAttempt }) => {\n  console.log(`Retrying \"${testDescription}\" (attempt ${nextAttempt})`);\n});\n\ntestEvents.on(\"testRetried\", ({ testDescription, attemptNumber }) => {\n  console.log(`Retry attempt finished for \"${testDescription}\" (attempt ${attemptNumber})`);\n});\n\n// To run these tests: npx velocious test spec/path/to/your-test-spec.js","lang":"typescript","description":"Demonstrates project initialization, basic test structure with tagging, retries, and configuring test behaviors, including event listeners for test retries."},"warnings":[{"fix":"Always use the full path: `import { configureTests } from 'velocious/build/src/testing/test.js'` and `import { testEvents } from 'velocious/build/src/testing/test.js'`.","message":"Velocious uses specific internal paths for importing testing utilities like `configureTests` and `testEvents`. Importing these directly from the root 'velocious' package will fail or result in undefined behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your configuration is at the default path or explicitly call `configuration.setCurrent(yourConfigObject)` after importing it.","message":"Application configuration is expected in `src/config/configuration.js` by default. If placed elsewhere, it must be explicitly imported and set via `configuration.setCurrent()` early in the application bootstrap process.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"After a failed test run, always inspect `tmp/screenshots` for console logs, screenshots, and browser logs associated with the failures.","message":"When running tests, Velocious captures console output during failures. These logs are saved to `tmp/screenshots` alongside other failure artifacts. Developers might overlook checking this directory for detailed debugging information.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `npm install velocious` has completed successfully. Verify the import paths are exact, especially for internal modules like `velocious/build/src/testing/test.js`.","cause":"Incorrect import path or the package was not installed correctly.","error":"Error: Cannot find module 'velocious' or Cannot find module 'velocious/build/src/testing/test.js'"},{"fix":"Browser tests must be `*.browser-test.js` or `*.browser-spec.js`. Check `npx velocious test --tag` and `npx velocious test --exclude-tag` arguments, and ensure the file path is correct. Use `--groups` and `--group-number` carefully for parallel runs.","cause":"Incorrect test file naming convention, tag filtering, or test path specification.","error":"No tests found for the given criteria"},{"fix":"Make sure `src/config/configuration.js` exists and exports a default configuration, or explicitly import your configuration file and call `configuration.setCurrent(yourConfigObject)` at the very beginning of your application.","cause":"The application's configuration object was not properly imported or initialized using `configuration.setCurrent()` early enough in the application startup.","error":"ReferenceError: configuration is not defined"}],"ecosystem":"npm"}