# @omegacrm/lwc-doc-gen

> Documentation generation for Lightning web components

Latest version **0.0.1-alpha2** (published 2022-11-25) · ISC license · 0 weekly downloads

## Install

```sh
npm install @omegacrm/lwc-doc-gen
pnpm add @omegacrm/lwc-doc-gen
yarn add @omegacrm/lwc-doc-gen
bun add @omegacrm/lwc-doc-gen
```

Provides the command `lwc-docgen`.

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; large bundle; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.1-alpha2 |
| Published | 2022-11-25 |
| First published | 2022-11-25 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 8 |
| Unpacked size | 21.7 MB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | Marcos laso |
| Maintainers | jsoleromega, mlasomega |

## Links

- npm: https://www.npmjs.com/package/@omegacrm/lwc-doc-gen
- npm.io page: https://npm.io/package/@omegacrm/lwc-doc-gen

## Dependencies (8)

- [cac](https://npm.io/package/cac.md) ^6.7.12
- [lwr](https://npm.io/package/lwr.md) ^0.8.6
- [chalk](https://npm.io/package/chalk.md) ^5.1.2
- [globby](https://npm.io/package/globby.md) ^13.1.2
- [fs-extra](https://npm.io/package/fs-extra.md) ^10.0.0
- [js-beautify](https://npm.io/package/js-beautify.md) ^1.14.0
- [fast-xml-parser](https://npm.io/package/fast-xml-parser.md) ^4.0.2
- [web-component-analyzer](https://npm.io/package/web-component-analyzer.md) ^1.1.6

## Recent versions

- 0.0.1-alpha2 (latest) — 2022-11-25
- 0.0.1-alpha1 — 2022-11-25

## README

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](#configuration)


# 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
```

---
_Source: https://npm.io/package/@omegacrm/lwc-doc-gen · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._