@zappar/parcel-transformer-mattercraft

@zappar/parcel-transformer-mattercraft

Overview

The @zappar/parcel-transformer-mattercraft plugin is a Parcel transformer designed to enhance the development of Mattercraft projects. With this plugin, you can build your projects outside of the Mattercraft environment, which is particularly useful for integrating into CI/CD pipelines.

This transformer specifically handles the conversion of .zcomp files into JavaScript and automatically generates corresponding .d.ts files.

Table Of Contents

Click to expand table of contents

Prerequisites

Before you can use this plugin, make sure you have Parcel installed.

If you haven't installed Parcel yet, you can do so via npm:

npm i --save-dev parcel

Installation

To install the @zappar/parcel-transformer-mattercraft plugin, run the following command in your project directory:

npm i --save-dev @zappar/parcel-transformer-mattercraft

Configuration

After installation, you need to set up your Parcel configuration.

Parcel Configuration

Create a .parcelrc file in your project root with the following content:

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.zcomp": ["@zappar/parcel-transformer-mattercraft"]
  }
}

This configuration tells Parcel to use the @zappar/parcel-transformer-mattercraft for handling .zcomp files.

Usage

Adding Build and Start Scripts

In your package.json, add build and start scripts to leverage Parcel:

"scripts": {
  "start": "parcel serve ./src/index.html",
  "build": "parcel build ./src/index.html"
}

Replace ./src/index.html with the path to your project's entry file.

Running Your Project

To start your development server, run:

npm run start

To build your project for production, run:

npm run build

Example Repository

To help you get started with the @zappar/parcel-transformer-mattercraft plugin, we have created an example project that demonstrates its use in a real-world scenario. This example repository showcases how to set up and serve a Mattercraft project using Parcel along with our plugin.

The project was initially exported from Mattercraft and includes features like HTML UI integration within a Mattercraft scene. It also provides a detailed README to guide you through the setup, configuration, and usage, making it an ideal starting point for both beginners and experienced developers.

You can find the example project here: Mattercraft-Parcel Example

This example serves as a practical reference for understanding how to effectively use the @zappar/parcel-transformer-mattercraft in your projects.

Caveats

HTTPS

If your Mattercraft project requires access to the device's camera, it's important to note that most modern browsers require a secure context (https) for camera access. To ensure your project works correctly during development, you will need to set up HTTPS serving for your Parcel server.

Add the --https flag to your start script. This will make Parcel serve your project over HTTPS:

"scripts": {
  "start": "parcel serve ./src/index.html --https",
  "build": "parcel build ./src/index.html"
}