Getting started on Salesforce

Requirements

• A Salesforce DX project (it has an sfdx-project.json)

• The Salesforce CLI (sf) and an authorized org

• Node.js 18 or newer, to run the fandry CLI

Native shadow DOM, whatever your org uses

1. Install the CLI

Install fandryui as a dev dependency. It is only used to run the fandry CLI and to copy source out of; nothing from node_modules is deployed.

npm install --save-dev fandryui

Prefer not to install it? Every command below also works as npx fandryui <command>.

2. Initialize

Fandry gets its own package directory next to your app code, so the copied source is easy to tell apart and can be deployed on its own.

npx fandry init

{
  "packageDirectories": [
    { "path": "force-app", "default": true },
    { "path": "fandryui" }
  ],
  "namespace": "",
  "sourceApiVersion": "67.0"
}

Use --dir <path> to install into a different package directory. Your existing indentation and default package directory are left untouched.

3. Add components

Name the components you want. Their dependencies are followed for you: adding table also adds input, checkbox, pagination, skeleton, the shared base and more.

npx fandry add button input table

Added 10 bundle(s) to fandryui/main/default/lwc (3 requested, 7 dependencies)
  + fandryBase
  + fandryButton
  + fandryLabel
  + fandryInput
  + fandryCheckbox
  + fandryPagination
  + fandrySkeleton
  + fandryTableCore
  + fandryTableState
  + fandryTable

npx fandry list                  # every component and what it depends on
npx fandry add --all             # everything
npx fandry add table --dry-run   # show what would be added
npx fandry add table --overwrite # replace table even if you edited it

Each bundle gets a .js-meta.xml using your project's sourceApiVersion, and it is never rewritten after that, so you can expose a component or add targets safely. Bundles you have edited are never overwritten unless you name them with --overwrite.

What your project looks like

my-sfdx-project/
├── sfdx-project.json          # "fandryui" package directory added by `fandry init`
├── fandry.json                # written by `fandry init`
├── package.json
├── force-app/                 # your app
│   └── main/default/lwc/
│       └── myComponent/
└── fandryui/                  # Fandry: your source now, commit it
    └── main/default/lwc/
        ├── fandryBase/        # shared class, base.css, tokens.css, motion.css
        ├── fandryButton/
        ├── fandryInput/
        ├── fandryLabel/
        ├── fandryCheckbox/
        ├── fandryPagination/
        ├── fandrySkeleton/
        ├── fandryTable/
        ├── fandryTableState/
        └── fandryTableCore/   # @tanstack/table-core, bundled

The copied files are yours: commit them, edit them, deploy them. They are ordinary LWC source, not a managed package.

Make it yours: CSS, then slots, then your own copy

4. Use a component

On the platform your code lives in the default c namespace, so fandryButton is <c-fandry-button>. No imports are needed in the template.

<template>
  <lightning-card title="Team">
    <c-fandry-button onclick={handleSave}>Save</c-fandry-button>

    <c-fandry-table
      columns={columns}
      data={rows}
      caption="Team members"
      enable-pagination
      page-size="3"
      enable-global-filter
    ></c-fandry-table>
  </lightning-card>
</template>

import { LightningElement } from 'lwc';

export default class MyComponent extends LightningElement {
  columns = [
    { id: 'name', accessorKey: 'name', header: 'Name' },
    { id: 'role', accessorKey: 'role', header: 'Role' }
  ];
  rows = [
    { name: 'Ada Lovelace', role: 'Engineer' },
    { name: 'Alan Turing', role: 'Researcher' }
  ];

  handleSave() {}
}

5. Deploy

Deploy Fandry first (or both directories in one command), then your app.

sf project deploy start --source-dir fandryui --target-org my-org
sf project deploy start --source-dir force-app --target-org my-org

# or both at once
sf project deploy start --source-dir fandryui --source-dir force-app --target-org my-org

Tested on a real org

Good to know

select, combobox, command and lookup use dynamic components

• Fandry is not a managed package. Components are plain c-namespace source in your project.

• The table depends on @tanstack/table-core. Because npm packages cannot be imported on the platform, fandry add table installs it as the fandryTableCore bundle.

• Upgrading: update fandryui, then run fandry add <name> again. Bundles you have not edited are updated to the new version, edited ones are skipped, and --overwrite replaces only the components you name. Commit fandry.json: it records what was installed so an upgrade can be told apart from an edit.