💡 This section can be skipped at first reading. You can proceed to the next section.
The client and backend subprojects are described below. Each subproject supports execution of the following commands/scripts:
yarn compile
yarn lint
yarn test
yarn dev
along with additional commands described in this section.
The client subproject:
- Starts webpack-dev-server listening on port 8080 in the development mode.
- Creates build artifacts (html files, script bundles and source maps) in the production mode. The artifacts are meant to be copied over to the backend subproject to be served by Express in full stack deployments.
- Additionally can start an instance of Chrome controlled via Inspector protocol (with caching disabled for better debugging) and point it to either webpack-dev-server or the backend server.
webpack-dev-server can be referred to as 'devserver'.
The backend subproject:
- In the production mode starts Express listening on port 3000 to serve from disk the build artifacts created by the client subproject .
- In the development mode starts Express listening on the same port and working as a proxy for webpack-dev-server.
- Implements HTTP caching arrangement which disables the caching for .html files and enables it for script bundles. A typical React application comes with .html files that are rather small whereas the bundles can be significantly larger. On the other hand, the build process keeps the names of .html files static and embeds a hash into the names of script bundles. As a result the caching arrangement ensures smooth deployment of versioning changes.
In case there are any changes made to the SPA Configuration block and the changes are recent (e.g. no client and backend builds have been performed since then), execute the yarn build command at the workspace level before starting the debugging configurations described below in the Client and Server Usage sections.
To start with client scenarios open the client subdirectory in VS Code. Then open the Terminal.
Execute in Terminal: yarn dev. Wait until the command finishes.
Start a browser and point it to localhost:8080. You should see the First SPA overview page.
VS Code: Open src/components/Overview.tsx and alter the text on the page. As you type, note the compilation progress in the Terminal followed by automatic browser refresh. The newly typed content should be shown on the overview page. If instead of starting a browser you used already running instance, then you might need to refresh the browser to get Live Reloading working.
To finish, press Control+C in the Terminal.
When to use: Develop the part of UI that doesn't need backend data.
VS Code: Start the Launch Chrome Connected to Devserver debugging configuration.
Wait until an instance of Chrome starts and shows the overview page.
VS Code: Put a breakpoint on the following line: src/components/ComponentB.tsx:14.
Use the overview page menu to choose the ComponentB. The breakpoint in VS Code will be hit. Press F5 to continue execution. Alternatively use Chrome to continue execution. Note Live Reloading is supported.
To finish, remove the breakpoint and stop the running debugging configuration (use Debugging toolbar or press Shift+F5).
When to use: Troubleshoot the client provided backend data is not required.
Follow the "Debug client using devserver and VS Code" scenario to see the overview page.
In the instance of Chrome started, open Chrome DevTools.
Use 'Sources -> Filesystem -> Add folder to workspace' to add client/src directory. In this directory open the file src/components/ComponentB.tsx and put a breakpoint on the line 14.
Use the overview page menu to choose the ComponentB. The breakpoint in Chrome DevTools will be hit. Go to VS Code and note it knows the execution has stopped on this line of code and lets you inspect variables. Use Chrome or VS Code to continue execution. Note Live Reloading is supported.
To finish, remove the breakpoint and stop the running debugging configuration (use Debugging toolbar or press Shift+F5).
When to use: Troubleshoot UI, inspect DOM tree, etc.
To perform the development build execute in Terminal: yarn build. The build artifacts can be found under client/dist directory.
To start the production build execute in Terminal: yarn build:prod. The build artifacts including the bundles with various compressions can be found under the same directory. If a bundle is too small to benefit from compression then it won't be compressed.
When to use: For Jamstack builds and deployments. For full stack builds, this step will be executed automatically by the backend usage scenarios below when needed.
Terminal: yarn test
VS Code: Put a breakpoint in any .test.tsx file.
VS Code: Start 'Debug Jest Tests' debugging configuration. Wait until the breakpoint is hit.
To finish, remove the breakpoint and stop the running debugging configuration (use Debugging toolbar or press Shift+F5).
Terminal: yarn lint
The same Express server is used in production and debugging.
This is done to keep the difference between production and debugging environments to the minimum. If the difference is significant then it could be difficult to debug customer issues. You might be unable to even reproduce it.
In some of the debugging scenarios another process, webpack-dev-server, is automatically started in background to facilitate debugging and recompile the client code as you type changes. But importantly the browser you use for debugging 'doesn't know' about that because it 'can see' Express only.
Open a command prompt in the directory containing the workspace file crisp-react.code-workspace .
Execute command: yarn build:prod.
When to use: Prior to backend deployment, for example before copying the backend to the filesystem of a Docker container.
Open a command prompt in the directory containing the workspace file crisp-react.code-workspace .
Execute command: yarn start:prod. It will build both the client application and the backend.
To run without build execute: yarn run:prod.
To stop the backend terminate the running command e.g. press Control+C.
Open the workspace file crisp-react.code-workspace in VS Code.
Start the debugging configuration Debug Client and Backend (workspace).
Wait until an instance of Chrome starts. You should see the overview page.
VS Code: Open client/src/components/Overview.tsx and alter the text on the page. After a few seconds delay the new content should be shown in the browser.
To finish, stop the running debugging configuration (use the ‘Stop’ button on VS Code Debugging toolbar two times or press Control+F5 twice).
Open a command prompt in the server subdirectory.
Execute command: yarn test
Open the server subdirectory in VS Code.
Put a breakpoint in .test.tsx file.
Start 'Debug Jest Tests' debugging configuration. Wait until the breakpoint is hit.
To finish, remove the breakpoint and stop the running debugging configuration.
Open a command prompt in the server subdirectory.
Execute command: yarn lint
Open the workspace file crisp-react.code-workspace in VS Code.
Start the debugging configuration Debug Client and Backend (workspace).
Wait until an instance of Chrome starts. You should see the overview page.
Using VS Code example:
Note that VS Code can mark a breakpoint with a circle that is grey and hollow rather than red and solid, referring to it as 'Unverified breakpoint'. You can check the breakpoint has been set and marked with solid red circle by highlighting the relevant process (client or server) on VS Code Debug sidebar in the CALL STACK view.
Put a breakpoint on the following line:
server/src/Server.ts:59.In the browser choose the ComponentC from the menu, the breakpoint will be hit. Remove the breakpoint and resume the execution.
Put a breakpoint on the line
client/src/components/ComponentB.tsx:14.Use the menu to go back to the First SPA and then choose the ComponentB. The breakpoint will be hit. Remove the breakpoint and resume the execution. Choose the ComponentA from the menu.
Using Chrome DevTools example:
In the instance of Chrome started, open Chrome DevTools.
Use 'Sources -> Filesystem -> Add folder to workspace' to add
client/src directory. In this directory open the file src/components/ComponentB.tsx and put a breakpoint on line 14.Use the overview page menu to choose the ComponentB. The breakpoint in Chrome DevTools will be hit. Remove the breakpoint and use Chrome or VS Code to continue execution.
To finish, stop the running debugging configuration (use the ‘Stop’ button on VS Code Debugging toolbar two times or press Control+F5 twice).
Open the workspace file crisp-react.code-workspace in VS Code.
Edit file client/webpack.config.js to change the sourceMap setting of the TerserPlugin config to true.
Start the debugging configuration Debug Production Client and Backend (workspace).
Wait until an instance of Chrome starts. You should see the overview page. Now you can use VS Code to set breakpoints in both client and backend provided the relevant process is highlighted/selected as explained in the previous scenario. You can also use Chrome DevTools to debug the client application as shown above.
To finish, stop the running debugging configuration (use the Debugging toolbar or press Control+F5 once).
Back to the README.