j-component: WeChat Mini Program Component Framework for Web

Common errors

• TypeError: jComponent.register is not a function

  cause The jComponent object was not imported correctly, or the module was not bundled/loaded as expected in the environment.
  fix Ensure `import jComponent from 'j-component';` is at the top of your file. If using CommonJS, `const jComponent = require('j-component');` must be used. Verify your bundler (e.g., Webpack, Rollup) is correctly processing the module.

• Failed to resolve component 'my-child'. Please check 'usingComponents' configuration.

  cause A component used in a template was not declared in the `usingComponents` object of the parent component, or the ID/path was incorrect.
  fix Ensure that every custom component used within a template is explicitly listed in the `usingComponents` object with its correct `id` (if globally registered) or `componentId` (returned from `jComponent.register`).

• WXML template parsing error: Invalid character in tag name.

  cause The `template` string provided to `jComponent.register` contains malformed WXML (or HTML) syntax, such as invalid tag names or unclosed tags.
  fix Review the `template` string for syntax errors. Ensure it adheres to valid WXML/HTML structure. Pay attention to custom component tags and ensure they are correctly formed.

Warnings

• gotcha The framework's performance is not equivalent to the native WeChat Mini Program implementation. It may exhibit slower rendering or update speeds.
  Fix: Optimize component logic and DOM manipulation within the j-component framework where possible, but acknowledge inherent performance trade-offs compared to native.
• gotcha j-component does not implement the full feature set of the native WeChat Mini Program. Some advanced or niche Mini Program features might be absent or behave differently.
  Fix: Carefully review the j-component documentation and test your Mini Program components thoroughly in the web environment to identify any unsupported features or behavioral discrepancies.
• gotcha j-component is an independent implementation and not a direct subset or equivalent of the native Mini Program. Do not assume 100% compatibility or identical behavior across all scenarios.
  Fix: Treat j-component as a close replica for web-based development and testing, but always perform final validation in the actual WeChat Mini Program environment for production readiness.

Install

• npm install j-component npm
• yarn add j-component yarn
• pnpm add j-component pnpm

Imports

• jComponent
  wrong:

  const jComponent = require('j-component');

  correct:

  import jComponent from 'j-component';

  While the README uses CommonJS `require`, modern TypeScript and ESM projects should use a default import for the main library object.
• Component

  import type { Component } from 'j-component';

  Import the `Component` type for type annotations if working with component instances.
• BehaviorDefinition

  import type { BehaviorDefinition } from 'j-component';

  Import `BehaviorDefinition` for defining component behaviors with type safety.

Quickstart

This quickstart demonstrates defining a behavior, registering global and custom components, creating an instance, and interacting with its methods and data. It shows how Mini Program component logic translates to the web context.

import jComponent from 'j-component';

// Define a behavior
const myBehavior = jComponent.behavior({
  data: { behaviorText: 'Hello from behavior' },
  methods: {
    logBehavior: function() {
      console.log('Behavior method called:', this.data.behaviorText);
    }
  }
});

// Register a global component 'my-view'
jComponent.register({
  id: 'my-view',
  tagName: 'wx-view',
  template: '<div style="border: 1px solid green; padding: 10px;"><slot/></div>'
});

// Register a custom component 'my-child-component'
const childComponentId = jComponent.register({
  tagName: 'my-child',
  template: '<my-view>Child Component Content: {{text}}</my-view>',
  properties: { text: String },
  behaviors: [myBehavior],
  methods: {
    onTap: function() {
      console.log('Child tapped!');
      this.triggerLifeTime('customEvent', { detail: 'data' });
    }
  }
});

// Register a root component that uses the child component
const rootComponentId = jComponent.register({
  template: '<my-child id="myChild" text="Initial Text"></my-child>',
  usingComponents: {
    'my-child': childComponentId
  },
  ready: function() {
    const child = this.querySelector('#myChild');
    if (child) {
      child.instance.logBehavior();
      child.setData({ text: 'Updated Text from Parent' }, () => {
        console.log('Child data updated.');
      });
      // Simulate an event
      child.dispatchEvent('touchstart', { touches: [{ x: 0, y: 0 }] });
    }
  }
});

// Create an instance of the root component
const rootComponentInstance = jComponent.create(rootComponentId);

// Append the component's DOM to the document body (for browser environments)
document.body.appendChild(rootComponentInstance.dom);

console.log('Root Component JSON:', rootComponentInstance.toJSON());