From 2b448cf0b2dd12135c7ded09fe839b875f849589 Mon Sep 17 00:00:00 2001 From: dc2007git Date: Mon, 30 Oct 2023 09:38:43 +0000 Subject: [PATCH] Creates a tutorial on React.js, initialising the Growth Charts on the local system using Storybook, using Next.js to create a react app --- docs/integrator/react-setup/component.md | 110 ++++++++++++++++++ .../integrator/react-setup/nextjs-tutorial.md | 29 +++++ mkdocs.yml | 4 +- 3 files changed, 142 insertions(+), 1 deletion(-) create mode 100644 docs/integrator/react-setup/component.md create mode 100644 docs/integrator/react-setup/nextjs-tutorial.md diff --git a/docs/integrator/react-setup/component.md b/docs/integrator/react-setup/component.md new file mode 100644 index 0000000..6a429a8 --- /dev/null +++ b/docs/integrator/react-setup/component.md @@ -0,0 +1,110 @@ +--- +title: Loading the React Component, using Storybook +reviewers: Danny Cowen +--- + +In this section, we will create a demo of the fully interactive React component on your local machine. We use Storybook as a shell +in which to load the React component. + +# Setting up your first React app + +When using React, it is best practice to also use a software called Node.js. Node.js enables React apps to communicate with the server, which means that complex operations that lie outside of frontend development are dealt with seamlessly. + +We will now walk you through installing Node.js. Best practice is again to install a program called Node Version Manager, or nvm for short. nvm allows the user to switch between different versions of Node.js, which is important because different React apps may require different versions of Node.js to run as intended. Therefore, nvm is an important tool to use whenever using React! + +!!! tip "nvm installation" + The Github page for nvm is where these instructions have been written from. It offers more in-depth troubleshooting, but for the sake of simplicity, we will list the essential instructions for nvm installation. + Reference: https://github.com/nvm-sh/nvm + +# Installing nvm + +1. ###Run the following install script: +```console +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash +``` +You now should have a hidden repository, accessible at `~/.nvm` + +1. ###Check the install worked: +```console +open ~/.zshrc +``` +Execute the above command in your Terminal. This should place you in a file used by your Terminal to execute commands, known as the Shell file. + + !!! warning + If you use bash as your shell, you may need to substitute `~/.zshrc` for `~/.bashrc` or `~./bash_profile`. Again, the nvm Github page has more specific troubleshooting for this. + +1. ###Troubleshooting the shell (`~/.zshrc`, `~/.bashrc` etc.) file: +You should see the following script somewhere in your shell file: +```console +export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" +[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm +``` +If it isn't there, copy the above script and paste it in the shell file. Then, execute the following command to save your changes (replace `~/.zshrc` with whichever shell file you use): +```console +source ~/.zshrc +``` + +1. ###Checking the install worked: +Make sure that you close the Terminal, and reopen it. You should now be able to type the following command, and receive a version number back: +```console +nvm -v +``` + +1. ###Installing Node.js via nvm: +For macOS/Linux users: +```console +nvm install --lts +``` +For Windows users: +```console +nvm install lts +``` + + !!! tip "LTS" + 'lts' stands for long-term support. This means that the developers of the software will commit to maintaining a stable release of that version, so you know it will be supported throughout your usage of it. + + +# Installing the React component + +In order to load the React component, you must open a new Terminal (MacOS)/Command Prompt (Windows) in your code projects directory: + +```console +cd /User/YourCodeProjectsDirectory +``` + +Then, clone the remote repository from Github, in order to locally install the React component: +```console +git clone https://github.com/rcpch/digital-growth-charts-react-component-library.git +``` + +Move into the directory containing your new local repository: +```console +cd digital-growth-charts-react-component-library +``` + +Github uses branches in order for developers to deploy and maintain stable software. Enter the following command in your Terminal to +begin working with the code approved for Storybook use: + +```console +git checkout storybook-live +``` + +You have now completed the part of this tutorial dedicated to using Git! + +# Running the React component in Storybook + +1. ###Install package dependencies: +```console +npm install +``` +This ensures that the dependencies of the React component (as specified in package.json) are installed prior to running + +1. ###Opening Storybook: +```console +npm run storybook +``` +This should load a development server in your Terminal/Command Prompt. Copy the url, and paste it into your browser to interact with your new React component! + +!!! warning "Storybook in Safari" + Storybook may run into errors when using Safari. The RCPCH Incubator Team advise using a different browser, such as Google Chrome, to enable full functionality of the software. + \ No newline at end of file diff --git a/docs/integrator/react-setup/nextjs-tutorial.md b/docs/integrator/react-setup/nextjs-tutorial.md new file mode 100644 index 0000000..e07f785 --- /dev/null +++ b/docs/integrator/react-setup/nextjs-tutorial.md @@ -0,0 +1,29 @@ +--- +title: Next.js tutorial +reviewers: Danny Cowen +--- + +Next.js is a React framework commonly used by developers to create a React app in your IDE, taking the heavy lifting of doing so away from the developer. We will walk you through initialising and creating your first Next.js app. + +!!! tip "Next.js" + We highly recommend reading through the Next.js tutorial featured in the online documentation (https://nextjs.org/docs). + +# Setting up your Next.js app + +!!! warning "React tutorial" + If you haven't already followed the React tutorial on the previous page, please do so. It contains information about installing nvm, which contains Node.js and npm. + +1. Enter your code projects directory: + ```console + cd YourCodeProjectsDirectory + ``` +1. Run the following command: + ```console + npx create-next-app@latest + ``` + +1. Press `enter` when prompted to run Next.js with default dependencies. + +1. Open your IDE (preferably Visual Studio Code). + + Congratulations! Setting up a React app with Next.js really is that easy, which is one of the reasons it is so popular. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 5f03879..f36f3be 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,6 +30,9 @@ nav: - 'integrator/api-keys.md' - 'integrator/making-api-calls.md' - 'integrator/api-reference.md' + - React Setup: + - 'integrator/react-setup/component.md' + - 'integrator/react-setup/nextjs-tutorial.md' - 'integrator/support.md' - 'integrator/client-specification.md' - 'integrator/faqs-for-integrators.md' @@ -121,7 +124,6 @@ plugins: enable_creation_date: true - macros - search - - render_swagger - with-pdf: cover_title: RCPCH Digital Growth Charts cover_subtitle: Complete Documentation Manual