This boilerplate package was originally taken from the Jive
application that @heijoe originally developed as a stand-alone application.
This repo however, contains a much more stripped down version of that original work.
The intent for this package is to be used as more of a boilerplate / quick-start base application.
The #TEMPLATED_TODO
tag is located in several locations throughout this project. These are located in sections of the base application that should be modified when this base is used to create your own application.
So after cloning this repo for use with your own application, be sure to search all sources for this tag and update the placeholder values with you own.
- As a
#RoadMap
item, these templated todo's should likely be updated automatically via ayeoman
template generator ( or similar ).
This application is developed in a node
environment. Before you begin using this package please ensure you have node
correctly installed before attempting to build the application.
This application uses npm
for installing the needed dependencies. After checking out the sources, run the following command from the root folder:
$ npm install
This application uses gulp
, webpack
and TypeScript
transpilers for building the application.
Gulp has predefined tasks for most developer needs.
NOTE: If using Node.js version 17 or newer, you might run into the following error:
Error: error:0308010C:digital envelope routines::unsupported
This comes from the Webpack v4 we are forced to use (see below). This should not occur if using gulp since we are redefining crypto.createHash
in webpack configuration files.
If it still occurs however, you can either:
-
Downgrade to Node.js 16
-
Declare the following environment variable:
NODE_OPTIONS=--openssl-legacy-provider
-
Create a VS Code Workspace for the project and add the following lines to the
code-workspace
file:{ "settings": { "terminal.integrated.env.windows": { "NODE_OPTIONS": "--openssl-legacy-provider" } } }
For more info, see: https://stackoverflow.com/q/69692842/1288184
Watch: Running gulp without any arguments will build the application, and monitor the source files for changes. This will result in an automatic rebuild of the application when necessary.
$ gulp
Build: Builds the application into the /dist
folder.
$ gulp build
Clean: Empties the contents of the /dist
folder.
$ gulp clean
Clear Build: Empties the contents of the /dist
folder, then rebuilds the application.
$ gulp clean-build
Package: Creates a clean build, and then packages the /dist
folder as an mfappx application in /package
.
$ gulp package
The commands below will: clone the repo / install dependencies / package the mfappx / open the package directory in explorer.
$ git clone https://github.com/M-Files/UI.Template.TypeScript-React.git
$ cd shellui-react-ts-base
$ npm install
$ gulp package
$ cd package
$ explorer .
After this, you can install the application right away to see it in action.
When active development is ongoing, it is a hassle to make changes and re-install. Instead you should create a junction point from your %ProgramFiles%\%MFilesVersion%\Client\Apps\sysapps\your_app_name\
directory that points to the /dist
directory of the development repo.
This can be done using the following command ( running the command prompt as Administrator ):
$ mklink /J "%ProgramFiles%\M-Files\%MfilesVersion%\Client\Apps\sysapps\your_app_name" "C:\GIT\shellui-react-ts-base\dist"
Note: Please be sure to replace the your_app_name
with your actual app name and ensure the proper path to the dist
folder is used as well.
- In M-Files Desktop application modules (shellUI, vaultUI) the flavor of JavaScript is JScript and it is run in the Windows Scripting Host (WSH) environment
- In M-Files Desktop dashboards the JavaScript is run with the Internet Explorer JavaScript engine
- Both WSH and Internet Explorer provide a rather old version of JavaScript, this leads to the following limitations
- You'll need to use polyfills, shims and shams where needed
- Webpack 4 is the latest version of webpack that still makes bundles that work in M-Files Desktop - do not update to Webpack 5
- If using MUI (Material UI), use Material-UI v4 as v5 does not work correctly
- Other UI component libraries might not work correctly (Bootstrap for example)
- The compile time error checking is done by the TypeScript compiler
- Note that the code might still compile even if there are typing errors
- To get more strict error checking you can experiment with the following options in tsconfig.json under compilerOptions
- "strict": true,
- "strictNullChecks": true,
- "noImplicitThis": true,
- "noImplicitReturns": true,
- "noUnusedLocals": false,
- "noUnusedParameters": false,
- "strictFunctionTypes": true,
- "strictPropertyInitialization": true,
- In addition to the compile time error checking, the ESLint should show errors and warnings when
gulp lint
is run - Both TypeScript compiler and ESLint should show errors real time in Visual Studio Code