@omegacrm/lwc-doc-gen v0.0.1-alpha2

Utility to speed up developing, documenting and testing of LWC OSS. It also works with Salesforce (SFDX-based) project with some limitations.

It aims zero-configuration approach, but sometimes it will not be possible. See configuring generator

Installation

To start using the tool, just require it as a dev-dependency:

npm install --save-dev @omegacrm/lwc-doc-gen

The installation will provide an binary file to be used on, for example, your npm scripts

How it works

TODO - Expand this info

The tolls will work in 2 main steps:

• Generate LWC and Rollup configuration from your source files (components, examples and docs) to be consumed by a LWC app.

  • lwc.config.json info will be generated

• Create / update an LWC OSS app that will use generated config en previous step, and bundle/serve by Rollup in the same way.

Usage

CLI usage

TODO

Configuration

Documentation configuration is being made using a JSON file with the following strucuture:

{
  "title": "Omega LWC doc",
  "lib": ["quill", "chart.js", "papaparse", "@popperjs/core"],
  "statics": {
    "root": "./guides",
    "items": [
      { "title" : "Installation", "relativePath": "installation.html" },
      { 
        "title": "QuickStart",
        "items": [
          { "title" : "Installation", "relativePath": "installation.html" }
        ] 
      },
      { 
        "title": "Lwc OSS",
        "files": [
          { "title" : "Use of Salesforce API", "relativePath": "installation.html" }
        ] 
      }
    ]
  },
  "defaultCategory": "Base components",
  "categories": [
    { 
      "name": "Only in Platform",
      "elements": [
        "tiny-data-loader",
        "list-view"
      ]
    },
    { 
      "name": "Only in OSS",
      "elements": [
        "app-layout",
        "global-nav",
        "docked-nav",
        "drawer",
        "drawer-item",
        "oauth2-client",
        "records-list-view",
        "router-view",
        "salesforce-api"
      ]
    }
  ]
}

Include external libraries

To allow rollup to grab your library external dependencies, add a lib key to your JSON file with an array of external modules to be resolved by node-resolve Rollup plugin instead on LWC module resolver.

For example

Documenting components

Each LWC component should be annotated in a certain way to allow the tool to be able to extract a valid component manifest. The following example of a component annotated:

/**
 * My custom component  description
 * @element my-component
 * @slot default - The description of the default slot
 */
export default class MyComponent extends LightningElement {

    /**
     * Description of the property
     * @type {'shade'|'info'|'warning'|'error'}
     */
    @api myfixedstring = 'info'

    /**
     * Description of the property
     * @type boolean
     * @default false
     */
    @api mybool = false

    /**
     * Description of the property
     * @type string
     * @default ''
     */
    @api mystring = ''

    /**
     * Desc ription of my public method
     */
    @api
    myMethod() {

    }
}

TODO

Folder structure for a component

A simple example of a component folder structure to follow:

component
    |-- component.js
    |-- component.html
    |-- component.css
    |-- component.svg
    |-- component.preview.svg
    |-- __tests__
        |-- myComponentJestTest.js
    |-- __examples__
        |-- myExampleBase
            |-- myExampleBase.js
            |-- myExampleBase.html
            |-- myExampleBase.css
        |-- otherExample
            |-- otherExample.js
            |-- otherExample.html
            |-- otherExample.css
    |-- __docs__
        |-- mydoc.md
        |-- otherDoc.html
    |-- __mocks__
        |-- MyController.getRecords.js
    |-- __specs__
        |-- gettingRecords.js

The proposed structure is based on lightning-base-components source code. Each LWC can have several children folders:

• __examples__ folder containing LWC components implementing different use cases. Each component should follow the LWC folder structure convention.
• __mocks__ JS files to mock Apex actions or and so on for this specific component.
• __specs__ Containing JS files with E2E test, such as Playwright tests (not handled by this utility at this moment)
• __docs__ Containing HTML and/or Markdown files documenting the component

SFDX project settings

The utility can be used to document LWC under a SFDX project (with some limitations), but first need some extra setup to allow Apex actions and others to work properly.

Mocking Apex actions

By default, the generated LWC app will alias all Apex calls to a module raising an object representing AuraHandledException type.

To make you Apex call works, you should first mock them. To do so, you can create a __mocks__ folder in you LWC component folder, or directly on your lwc folder. The second one is preferred as you will be able to share the mocks between components.

Mocking wired Apex

TODO

Using your mocks with Jest

The mocks you create can be used also in your Jest tests. You just have to edit your Jest config and add the route to your mock in the moduleNameMapper section. For example:

const { jestConfig } = require('@salesforce/sfdx-lwc-jest/config');

module.exports = {
    ...jestConfig,
    modulePathIgnorePatterns: ['<rootDir>/.localdevserver'],
    moduleNameMapper: {
        '^@salesforce/apex/MyClass.getAccounts': '<rootDir>/force-app/main/default/lwc/__mocks__/MyClass.getAccounts.js'
    }
};

Add files to your ignore files

.gitignore

The temporal file/folder can be safely ignored by GIT as they will be re-generated when the doc runs again:

lwc-config.json # The file generated to alias all your modules and used by LWC compiler
.lwc-docgen # This folder will be used to stored the aliased modules generated for your proyect, for example the custom labels.

.forceignore (for SFDX projects)

Add your examples, tests, mocks and specs to your force ingnore file as they are not needed by Salesforce. You can also add the 'preview' icon, For example

**/__tests__/**
**/__examples__/**
**/__mocks__/**
**/__spec__/**
**preview.svg