Skip to content

Linking local dependencies

This guide explains how to link local dependencies into a Lime CRM solution.

Info

Linking local dependencies is super helpful when you're developing libraries and testing them in a solution. It's useful when doing end-to-end testing, debugging, and before making commits / PRs / releases.

The diagram below presents a convenient setup for most developers in Lime CRM:

---
title: Conceptual diagram of local development dependencies
---
graph LR
    subgraph lime-crm-components
        crm-components(package.json)
    end

    subgraph lime-web-components
        web-components(package.json)
    end

    subgraph solution-kulfon
        solution-python(pyproject.toml)
    end

    subgraph lime-crm
        crm-python(pyproject.toml)
    end

    subgraph lime-webclient
        webclient-python(pyproject.toml)
        webclient-js(package.json)
        webclient-webclient-js(webclient/package.json)
        webclient-admin-js(admin/package.json)
    end

    subgraph lime-core
        core-python(pyproject.toml)
    end

    solution-python -- poetry add --> crm-python
    crm-python -- poetry add --> webclient-python
    crm-python -- poetry add --> core-python
    webclient-python -- poetry add --> core-python
    web-components -- npm link --> crm-components
    crm-components -- npm link --> webclient-js
    webclient-js -. use from root .- webclient-webclient-js
    webclient-js -. use from root .- webclient-admin-js

    classDef python fill:green,color:white,stroke-width:0px;
    classDef js fill:blue,color:white,stroke-width:0px;
    class solution-python,crm-python,webclient-python,core-python python;
    class webclient-js,webclient-webclient-js,webclient-admin-js,web-components,crm-components js;

solution-kulfon here is an example solution created by running lime-project new solution.

Prerequisite

Ensure all projects are cloned and installed according to instructions which can be found in relevant repositories.

Setup

Setup consists of few steps that depend on each other. Linking all local dependencies is optional and you can skip linking any of npm module / Python package. In such case you need to do this consequently, so if you decide to not link e.g. local lime-web-components then you should not attach this module in lime-crm-components and lime-webclient, to have consistent setup. Also you can skip steps 4 and 5 if you are not using any "solution" and want to run lime-webclient directly.

1. Prepare lime-web-components and lime-crm-components for local development

  1. Navigate to lime-web-components/packages/lime-web-components folder.
  2. Build the project by running npm run build.
  3. Run npm link. This will register local lime-web-components in global node_modules.
  4. Navigate to lime-crm-components root folder.
  5. Run npm install.
  6. Run npm link @limetech/lime-web-components.
  7. Now local lime-crm-components should use local lime-web-components!
  8. Run npm link. This will register local lime-crm-components in global node_modules.
  9. Done! Now lime-web-components and lime-crm-components are ready to be linked to lime-webclient frontend applications! ✨

To verify that everything works as expected you can run npm list --global. It should look similar to:

/home/kulfon/.nvm/versions/node/v16.18.0/lib
├── @limetech/[email protected] -> ./../../../../../Projects/update_platform_docs/lime-web-components
├── @lundalogik/[email protected] -> ./../../../../../Projects/update_platform_docs/lime-crm-components
├── [email protected]
└── [email protected]

2. Linking lime-web-components and lime-crm-components to lime-webclient

  1. Navigate to the root folder of lime-webclient.
  2. Run npm install and npm link @limetech/lime-web-components @lundalogik/lime-crm-components.
  3. Now it is the time to build all frontend applications. In each of frontend/admin and frontend/webclient directories run:
  4. npm install
  5. npm run build

Done! Now all your frontend applications should use local lime-crm-components and lime-web-components! ✨

You can verify that by running npm list in lime-webclient root folder. It should look similar to:

lime-webclient@ /home/kulfon/Projects/lime-webclient
├── @limetech/[email protected]
├── @limetech/[email protected]
├── @limetech/[email protected] -> ./../lime-web-components
├── @lundalogik/[email protected] -> ./../lime-crm-components
├── @lundalogik/[email protected]
└── @lundalogik/[email protected]

3. Linking lime-core to lime-webclient

  1. Navigate to lime-webclient root folder.
  2. Run poetry add -e <path_to_local_lime-core_root> to use lime-core in editable development mode
  3. Run poetry install.
  4. Done! Now lime-webclient should use local version of lime-core! ✨

4. Linking lime-core and lime-webclient to lime-crm

  1. Navigate to lime-crm root folder.
  2. Run poetry add -e <path_to_local_lime-core_root> to use lime-core in editable development mode
  3. Run poetry add -e <path_to_local_lime-webclient_root to use lime-webclient in editable development mode
  4. Run poetry install.
  5. Done! Now lime-crm should use local versions of lime-core and lime-webclient! ✨

5. Linking lime-crm to solution-kulfon

  1. Navigate to solution-kulfon root folder.
  2. Run poetry add -e <path_to_local_lime-crm_root> to use lime-crm in editable development mode
  3. Run poetry install.
  4. Done! Now solution-kulfon should use local version of lime-crm! ✨

Running solution

Using full setup with solution-kulfon

  1. Navigate to lime-crm-components root folder and run npm start.
  2. In separate terminal navigate to lime-webclient/frontend/webclient and run npm start.
  3. In separate terminal navigate to lime-webclient/frontend/admin and run npm start (if you need the access to the admin page).
  4. In separate terminal navigate to solution-kulfon, make sure that FLASK_ENV=development is present in .env file, and run poetry run flask run or run the server in the debugging mode in VSCode.

Using lime-webclient only

  1. Navigate to lime-crm-components root folder and run npm start.
  2. In separate terminal navigate to lime-webclient/frontend/webclient and run npm start.
  3. In separate terminal navigate to lime-webclient/frontend/admin and run npm start (if you need the access to the admin page).
  4. In separate terminal navigate to lime-webclient and run poetry run flask run or run the server in the debugging mode in VSCode.

General notes

  1. pyproject.toml is versioned file, so make sure to not push changes that relate to linking local Python dependencies.
  2. Alternative way of linking local Python dependencies is running poetry add <path_to_dependency>. If you already have the remote package in your venv-folder you might have to remove it manually first.
  3. Running npm install after linking local JavaScript dependencies will reset them according to a project's package.json, so you will need to link them to a dependant project again.