{"id":15815,"library":"sarcina","title":"Sarcina Web Project Bundler","description":"Sarcina is a fully-automatic, zero-configuration web project bundler designed to prepare vanilla, non-framework web projects for production. It offers a simpler, faster alternative to complex bundlers like Webpack, specifically targeting projects that do not require constant re-building during development. Instead, Sarcina is intended for a single run prior to deployment. The current stable version is 1.7.6. Sarcina processes markup files, identifies CSS and JavaScript assets, creates optimized bundles, and re-inserts links to these new bundles. During this process, it minifies HTML, minifies and autoprefixes CSS, and minifies and transpiles JavaScript. This results in a distribution folder with fewer, smaller, and less complex files, significantly improving browser load times and user experience. Its primary differentiator is its \"works-out-of-the-box\" philosophy, eliminating the need for extensive configuration often associated with other bundlers.","status":"active","version":"1.7.6","language":"javascript","source_language":"en","source_url":"https://github.com/Vanilagy/Sarcina","tags":["javascript"],"install":[{"cmd":"npm install sarcina","lang":"bash","label":"npm"},{"cmd":"yarn add sarcina","lang":"bash","label":"yarn"},{"cmd":"pnpm add sarcina","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The 'sarcina' package primarily uses CommonJS for its programmatic API, as indicated by its 'main' entry. Use 'require' for direct programmatic access in Node.js environments. While ESM import might resolve in some Node.js configurations, 'require' is the canonical method.","wrong":"import bundleSarcina from 'sarcina';","symbol":"bundleSarcina","correct":"const bundleSarcina = require('sarcina');"},{"note":"For ESM projects, 'sarcina' likely provides a default export that Node.js can resolve for ESM imports. Ensure your project's 'package.json' has '\"type\": \"module\"' or use a .mjs file extension. If encountering 'Cannot use import statement outside a module' error, switch to CommonJS 'require' or configure your environment for ESM.","wrong":"const bundleSarcina = require('sarcina');","symbol":"bundleSarcina","correct":"import bundleSarcina from 'sarcina';"},{"note":"Sarcina is designed primarily as a command-line interface (CLI) tool for ease of use. The `npx` command executes the local package binary. Programmatic imports are for integrating its bundling capabilities into other Node.js applications, not for running the CLI itself.","wrong":"import { sarcina } from 'sarcina'; // For CLI execution","symbol":"Sarcina CLI","correct":"npx sarcina

"}],"quickstart":{"code":"import sarcina from 'sarcina';\nimport { fileURLToPath } from 'url';\nimport { dirname, join } from 'path';\nimport { mkdir, writeFile, rm } from 'fs/promises';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\n\nasync function setupAndBundle() {\n const srcDir = join(__dirname, 'src');\n const distDir = join(__dirname, 'dist');\n const cssDir = join(srcDir, 'css');\n const jsDir = join(srcDir, 'js');\n\n // Clean up previous runs and set up source directories\n await rm(distDir, { recursive: true, force: true });\n await rm(srcDir, { recursive: true, force: true });\n await mkdir(cssDir, { recursive: true });\n await mkdir(jsDir, { recursive: true });\n\n // Create sample HTML, CSS, and JS files\n await writeFile(join(srcDir, 'index.html'), `\n \n \n \n Sarcina Demo\n \n \n \n

Hello Sarcina!

\n \n \n \n `);\n\n await writeFile(join(cssDir, 'base.css'), `\n body {\\n font-family: sans-serif;\\n background-color: #f0f0f0;\\n color: #333;\\n }\\n h1 {\\n text-align: center;\\n color: #007bff;\\n }\n `);\n\n await writeFile(join(jsDir, 'main.js'), `\n console.log(\"Sarcina has bundled this page!\");\n document.addEventListener('DOMContentLoaded', () => {\n const heading = document.querySelector('h1');\n if (heading) {\n heading.textContent += ' (Bundled!)';\n }\n });\n `);\n\n console.log('Sample project created in ./src. Running Sarcina...');\n\n try {\n // Programmatic API: Assuming a default export function that takes an options object.\n // The `input` and `output` properties are inferred from common bundler patterns\n // and the package's description of processing 'markup files in a folder'.\n await sarcina({\n input: srcDir,\n output: distDir\n });\n console.log(`Bundling complete! Check '${distDir}' for results.`);\n } catch (error) {\n console.error('Sarcina bundling failed:', error);\n }\n}\n\nsetupAndBundle();\n","lang":"javascript","description":"This quickstart demonstrates programmatic usage of Sarcina to bundle a simple vanilla web project. It creates a source directory with HTML, CSS, and JavaScript files, then invokes the 'sarcina' function with input and output paths to generate an optimized 'dist' folder. It requires Node.js (with ESM support for this specific example) and 'sarcina' installed."},"warnings":[{"fix":"For framework-based projects, consider using their recommended build tools (e.g., Webpack, Vite, Parcel, or framework-specific CLIs) which are optimized for their ecosystems and development workflows.","message":"Sarcina is explicitly designed for 'regular vanilla non-framework web projects'. It may not work as expected or provide optimal results for projects built with frameworks like React, Vue, or Angular, which often require specialized build configurations and tools.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Integrate Sarcina as a final step in your CI/CD pipeline or run it manually before deploying. For local development, use a simple HTTP server or a lightweight dev server, avoiding constant re-bundling with Sarcina.","message":"Sarcina is 'intended to be run only when bundling a project for deployment, not constantly during development'. Its design prioritizes simplicity and final output optimization over rapid incremental builds or hot module reloading features typically found in development-focused bundlers.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Evaluate if Sarcina's default optimizations meet your project's specific requirements. For projects demanding fine-grained control over every aspect of the build process, a configurable bundler like Webpack or Rollup might be more suitable, albeit with increased setup complexity.","message":"As a 'zero-configuration' tool, Sarcina handles bundling and optimization with predefined defaults. This simplicity means less explicit control over advanced aspects like custom Babel presets, PostCSS plugins, or specific asset handling rules, which might be necessary for highly customized projects.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always pin to a specific major version (e.g., `^sarcina@1.x.x`) to prevent unexpected breaking changes. Consult the official GitHub repository for updated programmatic API documentation when upgrading major versions.","message":"The exact programmatic API (function name, arguments, return value) for 'sarcina' is not explicitly documented in the provided README. The quickstart assumes a default export function that takes an object with 'input' and 'output' paths. Changes to this inferred API in future major versions could break existing integrations.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"If installed locally, run with `npx sarcina

`. If you wish to use it globally, install with `npm install -g sarcina` (though `npx` is generally preferred for local installations).","cause":"The Sarcina CLI tool is not globally installed or not found in the system's PATH, or `npx` cannot locate it.","error":"sarcina: command not found"},{"fix":"Verify the input directory path is correct and exists relative to where you're running Sarcina (either via CLI or programmatically). Ensure there are no typos and the directory structure matches expectations.","cause":"The specified input directory either does not exist or the path provided is incorrect.","error":"Error: Input directory not found: "},{"fix":"Double-check the package's actual programmatic export. If `require('sarcina')` returns an object, try accessing a property like `sarcina.run()` or `sarcina.bundle()`. If using ESM `import`, ensure it's a default export, or try `import * as sarcina from 'sarcina';` and then `sarcina.default()` or `sarcina.run()`.","cause":"When using the programmatic API, the imported 'sarcina' might not be directly callable as a function, or it might be a module object requiring a specific property to be called (e.g., `sarcina.bundle()`).","error":"TypeError: sarcina is not a function"}],"ecosystem":"npm"}