Piral CLI Parcel Bundler Plugin

Common errors

• No bundler found for the current project.

  cause The `piral-cli` could not detect an installed bundler plugin (like `piral-cli-parcel`) in the project's `devDependencies`.
  fix Run `npm install piral-cli-parcel --save-dev` in the root of your Piral instance or pilet project to install the Parcel bundler plugin.

• Parcel build failed: Cannot find module 'some-external-package'

  cause Parcel v1's module resolution, especially for external dependencies in Piral, might fail to locate a required package.
  fix Ensure 'some-external-package' is correctly listed in your `package.json` `dependencies` (for the Piral instance or pilet). If it's a shared Pilet external, verify it's correctly declared and provided by the Piral instance. For complex resolution issues, review Parcel v1's documentation regarding externals or consider explicit aliases.

Warnings

• gotcha This plugin is specifically built for and relies on Parcel v1. Users expecting Parcel v2 features, bug fixes, or a more modern bundling experience may find limitations. Parcel v1 is no longer actively maintained by the Parcel team.
  Fix: If Parcel v2 or another bundler is required, consider using `piral-cli-webpack` or `piral-cli-esbuild` with custom configurations.
• gotcha The `piral-cli-parcel` plugin must be explicitly installed as a development dependency (`npm i piral-cli-parcel --save-dev`) within a Piral instance or pilet project for `piral-cli` to detect and use Parcel as the bundler. A global Parcel installation is not sufficient.
  Fix: Always install `piral-cli-parcel` in the `devDependencies` of your Piral or pilet project's `package.json`.
• breaking As of v0.15.0, the `piral-cli-parcel` package was moved to a dedicated repository. While this is generally transparent for npm installations, it could affect users who previously relied on internal paths or specific monorepo structures for direct imports or tooling integrations.
  Fix: Ensure you are installing `piral-cli-parcel` via npm and not relying on any direct file paths from a previous monorepo setup.

Install

• npm install piral-cli-parcel npm
• yarn add piral-cli-parcel yarn
• pnpm add piral-cli-parcel pnpm

Quickstart

This script demonstrates installing `piral-cli-parcel` into a new Piral instance project and verifies that Piral CLI commands like `piral build` now utilize Parcel v1 as the underlying bundler.

import { execSync } from 'child_process';
import path from 'path';

// This quickstart demonstrates how piral-cli-parcel enables Parcel v1 bundling
// for Piral CLI commands by installing it into a new Piral instance.

const projectName = 'my-parcel-app';
const projectDir = path.join(process.cwd(), projectName);

try {
  // Ensure piral-cli is installed globally (recommended for Piral development)
  console.log('Installing piral-cli globally...');
  execSync('npm install -g piral-cli@latest', { stdio: 'inherit' });

  // Create a new Piral instance project
  console.log(`\nCreating Piral instance: ${projectName}`);
  execSync(`piral new ${projectName} --template default --npm`, { stdio: 'inherit' });
  process.chdir(projectDir); // Change to the newly created project directory

  // Install piral-cli-parcel as a development dependency.
  // The presence of this package automatically configures `piral-cli` to use Parcel v1.
  console.log('\nInstalling piral-cli-parcel into the project...');
  execSync('npm install piral-cli-parcel --save-dev', { stdio: 'inherit' });

  console.log('\nConfiguration complete. Piral CLI commands will now use Parcel v1.');
  console.log('To start debugging your Piral instance: run `piral debug` from this directory.');
  console.log('To build your Piral instance for production: run `piral build` from this directory.');

  // Demonstrating a build command that completes quickly
  console.log('\nExecuting a Piral build command (using Parcel v1) to demonstrate functionality...');
  execSync('piral build --target release', { stdio: 'inherit' });
  console.log('\nBuild completed using Parcel v1. Check the `dist/release` directory.');

  console.log(`\nQuickstart finished. To clean up, run: rm -rf ${projectName}`);

} catch (error) {
  console.error('An error occurred during the quickstart setup or execution:', error);
} finally {
  process.chdir(process.cwd()); // Return to the original directory
}