Sarcina Web Project Bundler

Common errors

• sarcina: command not found

  cause The Sarcina CLI tool is not globally installed or not found in the system's PATH, or `npx` cannot locate it.
  fix If installed locally, run with `npx sarcina <input-dir> <output-dir>`. If you wish to use it globally, install with `npm install -g sarcina` (though `npx` is generally preferred for local installations).

• Error: Input directory not found: <path/to/src>

  cause The specified input directory either does not exist or the path provided is incorrect.
  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.

• TypeError: sarcina is not a function

  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()`).
  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()`.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• npm install sarcina npm
• yarn add sarcina yarn
• pnpm add sarcina pnpm

Imports

• bundleSarcina
  wrong:

  import bundleSarcina from 'sarcina';

  correct:

  const bundleSarcina = require('sarcina');

  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.
• bundleSarcina
  wrong:

  const bundleSarcina = require('sarcina');

  correct:

  import bundleSarcina from 'sarcina';

  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.
• Sarcina CLI
  wrong:

  import { sarcina } from 'sarcina'; // For CLI execution

  correct:

  npx sarcina <input-dir> <output-dir>

  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.

Quickstart

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.

import sarcina from 'sarcina';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
import { mkdir, writeFile, rm } from 'fs/promises';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

async function setupAndBundle() {
    const srcDir = join(__dirname, 'src');
    const distDir = join(__dirname, 'dist');
    const cssDir = join(srcDir, 'css');
    const jsDir = join(srcDir, 'js');

    // Clean up previous runs and set up source directories
    await rm(distDir, { recursive: true, force: true });
    await rm(srcDir, { recursive: true, force: true });
    await mkdir(cssDir, { recursive: true });
    await mkdir(jsDir, { recursive: true });

    // Create sample HTML, CSS, and JS files
    await writeFile(join(srcDir, 'index.html'), `
        <!DOCTYPE html>
        <html>
            <head>
                <title>Sarcina Demo</title>
                <link rel="stylesheet" href="css/base.css">
            </head>
            <body>
                <h1>Hello Sarcina!</h1>
                <script src="js/main.js"></script>
            </body>
        </html>
    `);

    await writeFile(join(cssDir, 'base.css'), `
        body {\n            font-family: sans-serif;\n            background-color: #f0f0f0;\n            color: #333;\n        }\n        h1 {\n            text-align: center;\n            color: #007bff;\n        }
    `);

    await writeFile(join(jsDir, 'main.js'), `
        console.log("Sarcina has bundled this page!");
        document.addEventListener('DOMContentLoaded', () => {
            const heading = document.querySelector('h1');
            if (heading) {
                heading.textContent += ' (Bundled!)';
            }
        });
    `);

    console.log('Sample project created in ./src. Running Sarcina...');

    try {
        // Programmatic API: Assuming a default export function that takes an options object.
        // The `input` and `output` properties are inferred from common bundler patterns
        // and the package's description of processing 'markup files in a folder'.
        await sarcina({
            input: srcDir,
            output: distDir
        });
        console.log(`Bundling complete! Check '${distDir}' for results.`);
    } catch (error) {
        console.error('Sarcina bundling failed:', error);
    }
}

setupAndBundle();