Development workflow with grunt - how to prevent reinstalling every time

[bandtank]

I cloned the espo repository to work on a new feature, which I would like to submit as a pull request. Everything works, but the development workflow is very inefficient. I must be missing something.

Every time I change the source files, I run grunt to build the application. Unfortunately, that requires reinstalling the application through the GUI. Are there other commands or is grunt the only available tool? I build extensions for espo using the espocrm-ext template repository, which has a much faster development workflow using node. I'm looking for something similar with the base repo.

The documentation does not say anything other than use grunt. I see a few subcommands in Gruntfile.js, such as internal, build, release, etc., but I don't know what they do or if any of the options align with my request.

In other words, what is the workflow for developers with the base repository?

[bandtank]

I've found that running grunt copy --force generally works as expected if you don't need to compile anything. The workflow is now edit, run the aforementioned grunt command, and test the application. I am all ears if there is a better way, but this is a massive improvement.

[yuri]

With developer mode enabled and a configured file watcher for JS files, you don't need to run any build after changes. Just open the location in your browser, no need to install.

[bandtank]

Got it. Thanks. I will do that.

[Kyle]

Hi,

Can you provide your end to end solution for how you achieved this? It would be very helpful to have a full example.

[yuri]

EspoCRM instance should just open from the project root directory (if the web server has access to it). You just need to enable the developer mode. This is the supposed workflow and how we've been always working. No need to run build between changes, except changes in JS files, that can be done automatically with the file watcher. The full solution is in the documentation.

[bandtank]

I was unfortunately not able to get that to work, so I have to build. I will try again when I have time and then post the results here.

[bandtank]

EspoCRM instance should just open from the project root directory (if the web server has access to it). You just need to enable the developer mode. This is the supposed workflow and how we've been always working. No need to run build between changes, except changes in JS files, that can be done automatically with the file watcher. The full solution is in the documentation.

I think I finally realized what you meant by this comment.

For a project in "test-ext", Apache should point at "test-ext/site/" as the root. All development should occur in "test-ext/site" instead of test-ext/src/". After the extension has been developed, copy the files to "test-ext/src/" and build the release. I have been working out of "test-ext/src/" instead of "test-ext/site/", which means files have to be copied and updated constantly. I interpreted "project root directoy" to be the root if the ext-template repository instead of EspoCRM's root directory in site/.

Please correct me if I'm wrong.

[yuri]

> All development should occur in "test-ext/site" instead of test-ext/src/"

No.

> I have been working out of "test-ext/src/" instead of "test-ext/site/", which means files have to be copied and updated constantly.

This is a proper way.

We should differentiate developing on Espo repository and on an extension repository.

For extension repository we do not run install every time.

1. Make some changes in the src directory.
2. Run node build --copy (can be automated with a file watcher).

Sometimes we also need to run php site/clear_cache.php.

[bandtank]

Kyle

Hi,

Can you provide your end to end solution for how you achieved this? It would be very helpful to have a full example.

I finally got this working in my environment (OSX 15.0). As Yuri suggested, it is pretty much exactly what the directions say, which you can read here. Here are my notes:

Step 0: Install mysql (I recommend using 8.x at this point in time) and create a schema called espocrm-fork:

$: mysql -u root
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1412
Server version: 8.0.39 Homebrew​

Use the root user without a password to make things easier

Step 1: Fork the repository on Github. The name of my repository is espocrm.

Step 2: Clone the repository. I used espocrm-fork as the name: git clone git@github.com:bandtank/espocrm.git espocrm-fork

Step 3: Install composer:

$: composer --version
Composer version 2.7.8 2024-08-22 15:28:36
PHP version 8.3.10 (/opt/homebrew/Cellar/php/8.3.10/bin/php)
Run the "diagnose" command to get more detailed diagnostics output.

Step 4: Install node/npm and nvm:

$: npm --version
10.7.0
$: node --version
v22.2.0
$: nvm --version
0.40.0​

Note: There are issues with newer versions of node on many systems, including Apple Silicon Macs. For a long time, I had to use node v16.x. I don't know if newer versions fully work yet, but I haven't noticed any problems with v22.x recently.

Step 5: Install grunt using npm install grunt:

$: grunt --version
grunt v1.5.3​

Step 6: Run composer install

Step 7: Run npm ci

Step 8: Configure Apache/httpd to serve the root of the project using Espo's instructions. Here are the key parts of the conf files for my environment:

/opt/homebrew/etc/httpd/httpd.conf:

...
Listen 80
...
# Virtual hosts
Include /opt/homebrew/etc/httpd/extra/httpd-vhosts.conf​
...

/opt/homebrew/etc/httpd/extra/httpd-vhosts.conf:

<VirtualHost *:80>
    ServerName dummy
    DocumentRoot /path/to/default/webserver/folder
</VirtualHost>

<VirtualHost *:80>
    ServerName espocrm-fork

    DocumentRoot ~/Repositories/espocrm-fork/
    Alias /client/ ~/Repositories/espocrm-fork/client/

    <Directory ~/Repositories/espocrm-fork/>
      AllowOverride all
      Require all granted
    </Directory>

    ErrorLog /opt/homebrew/var/log/httpd/espocrm-fork-error.log
    CustomLog /opt/homebrew/var/log/httpd/espocrm-fork-access.log combined
</VirtualHost>​​

Run the webserver using brew services httpd start. Check the configuration using apachectl -S:

$: apachectl -S
VirtualHost configuration:
*:80 is a NameVirtualHost
default server dummy (/opt/homebrew/etc/httpd/extra/httpd-vhosts.conf:6)
port 80 namevhost espocrm-fork (/opt/homebrew/etc/httpd/extra/httpd-vhosts.conf:53)
ServerRoot: "/opt/homebrew/opt/httpd"
Main DocumentRoot: "/opt/homebrew/Cellar/httpd/2.4.62/htdocs"
Main ErrorLog: "/opt/homebrew/var/log/httpd/error_log"
...​

Step 9: Configure hosts:

$: cat /etc/hosts
127.0.0.1 localhost
255.255.255.255 broadcasthost
::1 localhost

127.0.0.1 dummy
127.0.0.1 espocrm-fork

Step 10: Install Espo by visiting http://espocrm-fork/install.

Step 11: Open VS Code and install the extension called Run on Save.

Step 12: Save a workspace file and edit the settings for the workspace using > settings.json:


Add the relevant parts of the following code to your workspace file:

{
  "folders": [
      {
          "name": "espocrm-fork",
          "path": "../espocrm-fork"
      }
  ],
  "settings": {
    "emeraldwalk.runonsave": {
      "commands": [
          {
              "match": "client/.*",
              "cmd": "node js/transpile -f ${relativeFile}"
          }
      ]
    }
  }
}​​

Note: I save repositories in ~/Repositories and workspaces in ~/Repositories/vscode-workspaces, which is why the path has ../ at the beginning.

Step 13: Save a js file and check the Output tab:

Running on save commands...
*** cmd start: node js/transpile -f client/src/views/fields/datetime.js

transpiled: 1, copied: 0
Run on Save done.​

At this point, refreshing the browser should show the changes. I hope this helps.