Lucy-CLI

Motivation

Lucy-CLI was developed out of a personal need to gain full TypeScript support for Wix Velo projects. Typically, using Wix’s GitHub integration provides JSON docs and basic type support, but I aimed for a more integrated TypeScript experience, especially for larger projects that benefit from enhanced type safety.

Lucy, my loyal dog, accompanied me during long nights working on a major project where I developed this CLI. Her companionship and resilience inspired the name "Lucy-CLI."

CAUTION: Thing to keep in mind before using Lucy-CLI

This CLI is still in development and may have bugs. Please use it with caution. Libraries are expected to have the same folder structure as the main typescript folder except for the pages folder. (backend, public, styles) The lucy CLI is opinionated and may not work with all projects.

Yarn: Lucy-CLI is designed to work with yarn. It may not work with npm. Make sure you have yarn installed on your machine and it is set to version 3.

1yarn set <version> 

The composite and declaration tsconfig setting int need to be set to false in order to reexport types from the lib folder. This is not ideal but it is a limitation of the current version of the CLI.

Importing backend endpoint into the frontend Please be aware that the backend endpoint should be imported with the following code:

1// eslint-disable-next-line @typescript-eslint/ban-ts-comment
2//@ts-ignore
3import { initialize, InitResponse } from 'backend/lib/initialize.web';

Contributing

Contribution are welcome, issue and pull request and I will merge it if i see it fit.

What It Does

Lucy-CLI is designed to streamline the setup and management of TypeScript within Wix Velo projects, providing tools to enhance code quality and reduce development time. Here’s what it offers:

1. ESLint Configuration

• Adds ESLint with a default configuration (customizable post-init) to maintain consistent code style and prevent common errors.

2. Wix Type Definitions

• Exposes Wix type definitions located in .wix/types/wix-code-types, allowing direct import and access to the types for comprehensive TypeScript support.

3. Autocomplete and Type Mapping for Page Elements

• Maps Wix page elements to their respective types, so $w('element') calls have full TypeScript support, including autocomplete for properties and methods.

4. Git Submodule Support

• Includes support for git submodules, providing full type support within submodules and enabling the use of libraries and types across projects.

• To add a submodule, include the following in the lucy.json file:

  1"modules": {
  2  "<repoName>": {
  3      "url": "String",
  4      "branch": "String",
  5      "path": "String", // Optional, specifies the path where the submodule should be cloned
  6      "noCompile": true // Optional, if true, the module will not be compiled
  7  }
  8}

5. Configurable Setup

• After initialization, Lucy-CLI creates a lucy-config.json configuration file where you can modify settings, add dev packages, specify Wix packages, and configure git submodules.

6. Execute render functions

• Lucy-CLI can execute render functions located in the backend template folder, allowing you to test render functions locally.

-7. Compile SCSS files

• Lucy-CLI can compile SCSS files to CSS files.
• It compiles styles/global.scss file to global.css.

8. Wix NPM Package Installation

• Lucy-CLI can install Wix npm packages from the lucy.json file.

-9. Testing with Vitest

• Lucy-CLI can run tests with Vitest.
• It runs tests located backend folder with the file name ending with .spec.ts.
• it creates a code coverage report in the coverage folder in the lib folders and typescript folders.
• Vitest is looking for mokes in typescript folder and lib folder.
  • You can add additional mock folders in vitest.config.ts file.

10. Linting with ESLint

    • Lucy-CLI can lint the code with ESLint.
    • It uses the ESLint configuration in the .eslintrc.cjs file in the project directory.

11. Add git version during production build

    • Lucy-CLI can add the git version to the production build.
    • It adds the git version to the public/constant/env.ts file in the public folder under the key gitTag.

12. Use velo-sync to synchronize local collection with wix

    • Lucy-CLI can synchronize the local collection with the wix collection.
    • More information can be found in the velo-sync documentation.

13. Synchronize package.json with lucy.json

    • Lucy-CLI can synchronize dependencies from your project's package.json directly into the lucy.json configuration. The dependencies are mapped to wixPackages and devDependencies are mapped to devPackages.

14. Manage CLI Templates

    • Lucy-CLI uses a templates folder (~/.lucy-cli) to store default configurations and file structures for the init command. The templates command allows you to easily open and customize these templates.

Commands & Options

Lucy-CLI comes with a range of commands and options to help manage your Wix Velo project. Here’s an overview:

Commands

• init: Initializes the current folder as a Wix project, creating essential configuration files.
• dev: Starts the development environment, including setting up any required services for local development.
• build-prod: Builds the project in production mode, optimizing files for deployment.
• prepare: Re-runs initialization commands, useful for setting up a pre-configured environment.
• velo-sync: Synchronizes Wix collections.
• install: Installs all Wix and dev npm packages listed in the lucy.json file.
• fix: Runs a fix command to resolve common issues in development or production settings.
• docs: Generates documentation for the project.
• cypress: Starts the Cypress test runner.
• templates: Opens the Lucy CLI templates folder.
• sync-pkgs: Synchronizes dependencies from package.json to lucy.json.
• 🦮 e2e: Starts the Cypress test runner in CI mode.
  Usage: e2e <someKey> <someID>
  • someKey: The key for the test.
  • someID: The build ID for the test.

Options

• -h, help: Displays the help message with command descriptions.
• -v, version: Shows the current version of Lucy-CLI as defined in the project’s package.json.
• -f, force: Forces specific commands to execute, useful for deleting obsolete pages or initializing missing components.
• -l: Locks package versions to those specified in the configuration file during installation.

Examples

Here are some example commands to get started with Lucy-CLI:

1# Initialize a new Wix project
2lucy-cli init
3
4# Start the development environment
5lucy-cli dev
6
7# Synchronize database and settings
8lucy-cli sync
9
10# Install Wix npm packages from 'lucy.json' with locked versions
11lucy-cli install -l
12
13# Force start the dev environment
14lucy-cli dev -f
15
16# get help
17lucy-cli help
18
19🦮 Lucy CLI Help
20Usage: lucy-cli <command> [options]
21
22Commands:
23🦮 init               : Initializes a WIX project to enable full TS support.
24🦮 dev                : Starts the development environment. This includes setting up any required services for local development.
25🦮 build-prod         : Builds the project in production mode, optimizing files for deployment.
26🦮 prepare            : Prepares the project by installing packages & initializing git modules, configured in lucy.json.
27🦮 velo-sync          : Synchronizes Wix collections (run `velo-sync -h` for help).
28🦮 install            : Installs all Wix and dev npm packages listed in the 'lucy.json' file.
29🦮 fix                : Runs a fix command to resolve common issues in development or production settings.
30🦮 docs               : Generates documentation for the project.
31🦮 cypress            : Starts the cypress test runner.
32🦮 templates          : Opens the Lucy CLI templates folder.
33🦮 sync-pkgs          : Syncs dependencies from package.json to lucy.json.
34🦮 e2e                : Starts the cypress test runner in CI mode. Usage: `e2e <key> <buildId>`
35
36Options:
37🦮 -h, help           : Displays this help message.
38🦮 -v, version        : Displays the current version of Lucy CLI as defined in the project’s package.json.
39🦮 -f, force          : Forces specific commands to execute even if they may lead to potential issues.
40                      Used for functions like deleting obsolete pages or initializing missing components.
41🦮 -l                 : Locks package versions to those specified in `lucy.json` during installation.
42
43Examples:
44🦮 lucy-cli init       : Initializes a new Wix project.
45🦮 lucy-cli dev        : Starts the development environment.
46🦮 lucy-cli sync       : Synchronizes database and settings.
47🦮 lucy-cli install    : Installs all Wix and dev npm packages from 'lucy.json'.
48🦮 lucy-cli dev -f     : Starts the dev environment with forced settings.
49🦮 lucy-cli install -l : Installs Wix npm packages, respecting locked versions specified in the configuration.

If you find Lucy-CLI useful, consider supporting the project: