From f1e21e2abfe2198447a46861a0fec83d67405037 Mon Sep 17 00:00:00 2001 From: oanelson Date: Fri, 29 Nov 2024 16:27:01 -0800 Subject: [PATCH 1/9] Progress on #165 --- .../development-life-cycle.md | 27 ++++++------- .../development-standards.md | 38 +++++++++---------- .../service-worker-removal.md | 2 +- 3 files changed, 33 insertions(+), 34 deletions(-) diff --git a/docs/developer-documentation/building-your-application/development-life-cycle.md b/docs/developer-documentation/building-your-application/development-life-cycle.md index fad076b..c7392fb 100644 --- a/docs/developer-documentation/building-your-application/development-life-cycle.md +++ b/docs/developer-documentation/building-your-application/development-life-cycle.md @@ -5,34 +5,35 @@ description: Setting up web projects with RADFish # Project Setup -When setting up a web application within the NOAA ecosystem, it’s imperative that you setup your project properly in order to make life easier as development progresses. A strong setup includes proper development standards ie: File structure, linting, core frameworks, build tooling, etc. +When creating a web application in the NOAA ecosystem, take time to carefully set up your project. This will make ongoing development easier and reduce maintenance overhead. A proper setup follows best practices around file structure, linting, core frameworks, and build tooling. -For NOAA applications, tooling that supports full-featured web forms is a must. There are also branding/style guidelines and compliance regulations that must be adhered too. All of this must be considered when setting up a new project. +All new NOAA web applications must: -Setting up a project properly will improve developer velocity over the course of the project. In addition to this, it will limit maintenance overhead, especially if the project is setup using a standard environment and set of tools that are familiar to other NOAA developers. +- support full-featured web forms. +- adhere to compliance regulations. +- follow branding and style guidelines. +- use standard environments and tools that are familiar to other NOAA developers. -To setup a new NOAA web app project, we recommend following the instructions outlined in our [Getting Started](../getting-started) documentation. +To setup a new NOAA web app project, we recommend following [Getting Started](../getting-started) documentation. ## React Components The following components are included by default with the RADFish Framework. The components build upon the ‣ component library, which adheres to [USWDS standards](https://designsystem.digital.gov/). For detailed information on the available components and what attributes they accept, please see the official storybook documentation: [https://trussworks.github.io/react-uswds/](https://trussworks.github.io/react-uswds/) -**Why Use It** +###Why Use React? -- **Responsive Design**: Automatically adjusts for different screen sizes with a collapsible menu. -- **Customizable**: Allows for easy customization of navigation links. -- **Integrated Search**: Includes a search bar for added functionality. -- **Branding**: Supports branding elements like logos in the header. +- **Responsive Design.** Automatically adjusts for different screen sizes with a collapsible menu. +- **Customizable.** Allows for easy customization of navigation links. +- **Integrated Search.** Includes a search bar for added functionality. +- **Branding.** Supports branding elements like logos in the header. **Additional Notes** - The **`@trussworks/react-uswds`** package is a requirement for this component to ensure proper styling and functionality. This package is included by default. - Custom CSS can be applied for further customization. -**Resources** +##Resources -- [https://trussworks.github.io/react-uswds/?path=/docs/components-header--basic-header](https://trussworks.github.io/react-uswds/?path=/docs/components-header--basic-header) - -By integrating these components into your React application, you can create a professional and responsive UI with minimal effort. The **`Layout`** and **`HeaderNav`** components work together to provide a structured and navigable interface, enhancing the overall user experience. +By integrating the [header](https://trussworks.github.io/react-uswds/?path=/docs/components-header--basic-header) components into your React application, you can create a professional and responsive UI with minimal effort. The **`Layout`** and **`HeaderNav`** components work together to provide a structured and navigable interface, enhancing the overall user experience. --- diff --git a/docs/developer-documentation/building-your-application/development-standards.md b/docs/developer-documentation/building-your-application/development-standards.md index b578790..b603e0b 100644 --- a/docs/developer-documentation/building-your-application/development-standards.md +++ b/docs/developer-documentation/building-your-application/development-standards.md @@ -5,17 +5,15 @@ description: USWDS, NOAA branding and Styling, and 508 compliance # Development Standards -**USWDS** +## USWDS -USWDS (United States Web Design System) is a web design system that specifies coding patterns, components, and design tokens that outline how government applications should be built while adhering to 508 compliance guidelines. +The U.S. Web Design System (USWDS) is a set of design and development principles and guidelines. It helps deveolpers create standardized, accessible, consistent, and user-friendly websites and applications. It helps developers adhere to 508 compliance guidelines. -More specifically, when building applications with React, there is an existing component library, [react-uswds](https://github.com/trussworks/react-uswds) that our project extends for the purposes of building any RADFish application. These components maintain all functionality of `react-uswds` components, but are branded with NOAA themes and styles. These components live in `react-radfish` directory, and allow for development in a modern React environment with NOAA look and feel. +In most cases, RADFish uses standard components from the [`react-uswds`](https://github.com/trussworks/react-uswds) open source project. The RADFish project further extends the react-uswds library. These components maintain the functionality of react-uswds, but are branded with NOAA themes and styles. These components live in the [`react-radfish` directory](https://github.com/NMFS-RADFish/react-components). This allows modern React development with NOAA look and feel. -For reference on the full `react-uswds` library, you can reference the deployed storybook: +For information on the full `react-uswds` library, refer to their [storybook](https://trussworks.github.io/react-uswds/?path=/docs/welcome--docs). -[https://trussworks.github.io/react-uswds/](https://trussworks.github.io/react-uswds/?path=/docs/welcome--docs) - -The benefit of referencing and leveraging `react-radfish` when building applications is to increase developer velocity, design consistency, and ensures that front-end development is happening in compliance with government regulation. The storybook above provides examples of a wide variety of compliant components that can be used to build apps for a wide variety of use cases. +Building applications with `react-radfish` leads to faster development, consistent design, and ensures compliance with government regulations. The [`react-uswds` storybook](https://trussworks.github.io/react-uswds/?path=/docs/welcome--docs) provides examples of compliant components that can be used to build apps for various use cases. -**Example** +### Example If you wanted to build a `TextInput` component into an existing form, you can use the `@trussworks` [storybook reference](https://trussworks.github.io/react-uswds/?path=/docs/components-text-input--docs) related to component props that are available. @@ -47,14 +45,14 @@ import { TextInput, Label } from "@trussworks/react-uswds"; --- -### **NOAA Branding Guidelines and Style Guide** +## NOAA Branding Guidelines and Style Guide -Branding refers to the process of creating a distinct identity for a product or application. It involves defining and maintaining a set of visual elements, such as logos, colors, and typography, that represent the brand. +Branding creates a distinct identity for a product or application. It defines and maintains a set of visual elements that represent the brand. Branding can include logos, colors, and typography standards. -You will notice, that the components above do not have any `className` assigned, and you may be wondering how to style that component. To do this, there are a couple of things to keep in mind. +You might have noticed that the components above do not have any `className` assigned. You may be wondering how to style that component. There are a few things to keep in mind when styling components: -1. Each component in `react-radfish` has it’s own scoped css file, that modifies the existing `@trussworks` css in order to inject NOAA styles. This file should not be touched. If you notice a bug or issue, please see `CONTRIBUTING` -2. You can modify the general theme of these components in the `styles/theme.css` file. You can change things like color variables, font-family, and line-height here, and they will be propagated throughout the application, as well as throughout `react-radfish` . RADFish utilizes css variables, and can be used like so: +- Each component in `react-radfish` has it’s own scoped CSS file. This file modifies the existing `@trussworks` CSS to inject NOAA styles. This file should not be touched. If you notice a bug or issue, please consider [contributing to the project](https://nmfs-radfish.github.io/radfish/about/contribute). +- You can modify the general theme of these components in the `styles/theme.css` file. You can change things like color variables, font-family, and line-height here. They will be propagated throughout the application, as well as throughout `react-radfish`. RADFish uses CSS variables, like this: ```css // styles/theme.js @@ -68,7 +66,7 @@ You will notice, that the components above do not have any `className` assigned, } ``` -1. If you need to add additional styles to a particular component, you can do so by adding another `className` **after** the component has been imported from `react-radfish` +- If you need to add additional styles to a particular component, you can add another `className` **after** the component has been imported from `react-radfish`: ```jsx import { Label } from "@nmfs-radfish/react-radfish"; @@ -78,15 +76,15 @@ import { Label } from "@nmfs-radfish/react-radfish"; ; ``` -By following this method, you can leverage the underlying `uswds` component, maintain the NOAA theme, and can extend if further to suit you needs as a developer. +By following this method, you can use the `uswds` component, while still maintaining the NOAA themes. You can also extend it further to suit your needs as a developer. -**_508 Compliance (Section 508 of the Rehabilitation Act)_** +## 508 Compliance (Section 508 of the Rehabilitation Act) -508 compliance, also known as Section 508 compliance, refers to the adherence to accessibility standards outlined in Section 508 of the Rehabilitation Act. In the context of web development, it signifies the design and development of websites and digital content in a manner that ensures accessibility for individuals with disabilities. In a nutshell, this ensures that website can be navigated and understood by users with various disabilities, such as those with visual or auditory impairments. Developers must follow these guidelines to ensure their websites are accessible and usable by everyone, promoting an inclusive and diverse online experience. +Section 508 compliance refers to the adherence to accessibility standards outlined in [Section 508 of the Rehabilitation Act](https://www.section508.gov/). For web developers, it means designing and developing content that's accessible to individuals with disabilities. In other words, 508 compliant websites can be navigated and understood by users with various disabilities. For example, there are guidelines that aid those with visual or auditory impairments. Developers must follow these guidelines to ensure their websites are accessible and usable by everyone. This promotes an inclusive and diverse online experience. -As NOAA is a governmental agency, Section 508 compliance is crucial for the development of frontend apps because it ensures that these applications are accessible to all users, including those with disabilities. NOAA provides vital information related to weather, oceans, and atmospheric conditions, and it is imperative that individuals with diverse abilities can access and utilize these resources. +Because NOAA is a governmental agency, Section 508 compliance is required for the development of frontend apps. NOAA provides vital information related to weather, oceans, and atmospheric conditions. Individuals with diverse abilities need to access and use these resources. -508 compliance has been a driving factor for many decisions we make in RADFish, from extending a compliant component library in `@trussworks/react-uswds` to our UX strategies. +Section 508 compliance is a driving factor for many decisions we make in RADFish about our UX strategies. We have also extended a compliant component library in `@trussworks/react-uswds`. -**Resources:** +### Resources Read more about 508 compliance here: [https://www.section508.gov/](https://www.section508.gov/) diff --git a/docs/developer-documentation/building-your-application/service-worker-removal.md b/docs/developer-documentation/building-your-application/service-worker-removal.md index cfb5516..36866dd 100644 --- a/docs/developer-documentation/building-your-application/service-worker-removal.md +++ b/docs/developer-documentation/building-your-application/service-worker-removal.md @@ -5,7 +5,7 @@ title: Service Worker Removal ### Removing the Preconfigured Service Worker -> **Disclaimer:** The service worker in this template is designed to provide offline functionality and improve app performance. Removing it is generally not recommended; however, if needed, follow these steps: +> **Disclaimer:** The service worker in this template is designed to provide offline functionality and improve app performance. Removing it is generally not recommended. However, if needed, follow these steps: 1. **Uninstall the Service Worker Plugin** Run the following command to uninstall `vite-plugin-pwa`: From b548dad99d0c5e70a684a57c94e057f4ddf0e820 Mon Sep 17 00:00:00 2001 From: oanelson Date: Fri, 29 Nov 2024 17:21:25 -0800 Subject: [PATCH 2/9] Progress on #165 --- .../available-scripts/index.mdx | 6 +- .../available-scripts/installing-cli.md | 3 +- .../available-scripts/running-example.md | 6 +- .../patterns/state-management.md | 87 ++++++++++--------- 4 files changed, 51 insertions(+), 51 deletions(-) diff --git a/docs/developer-documentation/building-your-application/available-scripts/index.mdx b/docs/developer-documentation/building-your-application/available-scripts/index.mdx index 751a411..3a3100d 100644 --- a/docs/developer-documentation/building-your-application/available-scripts/index.mdx +++ b/docs/developer-documentation/building-your-application/available-scripts/index.mdx @@ -17,11 +17,11 @@ import DocCardList from '@theme/DocCardList'; **`npm start`** -This script starts the Vite development server. It runs the app locally with hot module reloading, allowing for fast development and instant updates as you make changes. Open [http://localhost:3000](http://localhost:3000/) to view it in the browser. +Starts the Vite development server. It runs the app locally with hot module reloading, allowing for fast development and instant updates as you make changes. Open [http://localhost:3000](http://localhost:3000/) to view it in the browser. **`npm run build`** -Builds the project for production by using Vite’s build tool. It generates optimized static assets, such as HTML, CSS, and JavaScript, which are output to the dist directory. +This script builds the project for production by using Vite’s build tool. It generates optimized static assets, such as HTML, CSS, and JavaScript, which are output to the dist directory. **`npm run prebuild`** @@ -45,7 +45,7 @@ Formats the code in the `src/` directory using Prettier according to the configu **`npm run serve`** -This script starts a local server to preview the production build. It serves the files from the `dist/` folder, allowing you to check how the app will behave in a production environment. +Starts a local server to preview the production build. It serves the files from the `dist/` folder, allowing you to check how the app will behave in a production environment. **`npm run lhci:mobile`** diff --git a/docs/developer-documentation/building-your-application/available-scripts/installing-cli.md b/docs/developer-documentation/building-your-application/available-scripts/installing-cli.md index 39a94e1..848ac06 100644 --- a/docs/developer-documentation/building-your-application/available-scripts/installing-cli.md +++ b/docs/developer-documentation/building-your-application/available-scripts/installing-cli.md @@ -4,7 +4,7 @@ sidebar_position: 1 # Installing the CLI -The RADFish CLI is available as an npm package, making the installation process much simpler. Follow these steps to install and use the CLI: +The RADFish CLI is available as an `npm` package, making the installation process much simpler. Follow these steps to install and use the CLI: ## Install the CLI @@ -21,4 +21,3 @@ create-radfish-app --version ``` This should display the version number of the installed CLI. - diff --git a/docs/developer-documentation/building-your-application/available-scripts/running-example.md b/docs/developer-documentation/building-your-application/available-scripts/running-example.md index 1aa0b8c..ba9f149 100644 --- a/docs/developer-documentation/building-your-application/available-scripts/running-example.md +++ b/docs/developer-documentation/building-your-application/available-scripts/running-example.md @@ -4,12 +4,12 @@ sidebar_position: 2 # Running an Example -RADFish ships with several different [boilerplate examples](../../examples-and-templates#examples) that demonstrate core pieces of functionality identified as critical for NOAA application development. You can use these examples as a reference point to build out your own implementation, or simply to get inspiration for your own design patterns with some pre-defined best practices. +RADFish ships with several different [boilerplate examples](../../examples-and-templates#examples) that demonstrate core pieces of functionality. These examples have been identified as critical for NOAA application development and demonstrate best practices. You can use these examples as a reference point to build out your own implementation. They can also serve as inspiration for your own designs. -For instance, there is an example that demonstrates how to build a multi-step form that caches each step within IndexedDB, so that it can be referenced without having network connection. In order to run this example, you can run the following command: +For instance, there is an example that demonstrates how to build a multi-step form that caches each step within IndexedDB. Cacheing allows data to be referenced without having a network connection. To run this example, use the following command: `npx @nmfs-radfish/create-radfish-app my-app --example multistep-form` This will clone the code from the `multistep-form` onto your machine, and spawn a new web process on port `3000` or another port if that is already taken. -Feel free to utilize this code and modify it for your needs! +Feel free to use this code and modify it for your needs! diff --git a/docs/developer-documentation/building-your-application/patterns/state-management.md b/docs/developer-documentation/building-your-application/patterns/state-management.md index edcabe9..2b0c2c4 100644 --- a/docs/developer-documentation/building-your-application/patterns/state-management.md +++ b/docs/developer-documentation/building-your-application/patterns/state-management.md @@ -5,34 +5,35 @@ description: An overview of managing application state effectively # State Management -**What is State Management?** +## What is State Management? -In the world of NOAA web app development, we frequently deal with various forms of data, from user inputs like form data to environmental statistics such as fish populations or weather changes. State management is our tool for keeping track of all these changes efficiently. Think of it as a digital notepad that records every update and change within the app, ensuring we always have the most current information at our fingertips. +NOAA web apps frequently deal with a variety of data. Data can range from user-generated form data to environmental statistics such as fish populations or weather changes. State management is our tool for keeping track of all these changes efficiently. Think of it as a digital notepad that records every update and change within the app. This ensures we always have the most current information at our fingertips. -**Why Use State Management in NOAA Apps?** +## Why Use State Management in NOAA Apps? -Our applications are not just repositories of static data; they are dynamic platforms where data constantly evolves. State management is essential for several reasons: +Our applications are not just repositories of static data. They are dynamic platforms where data constantly evolves. State management is essential for several reasons: -- **Stay Updated**: It allows us to display the most up-to-date information to our users, ensuring accuracy and reliability. -- **Work Offline**: It enables our apps to function even in the absence of an internet connection, storing data locally and syncing it back to our servers once a connection is re-established. -- **Be Fast and Responsive**: It helps our apps to react swiftly to user interactions and data changes, providing a smooth and efficient user experience. -A Simple Way to Manage State: Using React Context +- **Stay Updated.** Display the most up-to-date information to our users. This ensures accuracy and reliability. +- **Work Offline.** Our apps can function even without an internet connection. We do this by storing data locally and syncing it back to our servers once a connection is re-established. +- **Fast and Responsive.** Our apps to react swiftly to user interactions and data changes, providing a smooth and efficient user experience. -For sharing and managing state across different parts of our applications, we use a feature called React Context. This is akin to creating a communal space where any component of our app can easily access or update shared information, eliminating the complexity of passing data through multiple layers. +### A Simple Way to Manage State: Using React Context -**How We Implement State Management** +We use a feature called **React Context** to share and manage states across different parts of our applications. This creates a communal space where any component of our app can easily access or update shared information. This feature eliminates the complexity of passing data through multiple layers. -**FormState** +## How We Implement State Management -Our approach to managing form state is straightforward yet effective. Each form should maintain it's own state within the component itself. Note, that this is the recommended approach for managing a form's state, rather that reaching for a centralized state machine (think React Context or Redux) as it is more straightforward to implement without any excess layers of abstraction. +### FormState -The potential downside of this approach is that each form will have it's own state management implemented independantly, which could lead to less DRY code. This is an acceptable tradeoff in most cases, but if you notice that certain patterns should be shared among different components, you will either need to pass these state values as props to child components, or wrap the related components in a `ContextProvider` and expose them via the `useContext` hook. See more about how to use React Context [here](https://react.dev/reference/react/useContext). +Our approach to managing form state is simple yet effective. Each form should maintain it's own state within the component itself. This is the recommended approach for managing a form's state, rather that reaching for a centralized state machine like React Context or Redux. This approach is more straightforward to implement and removes excess layers of abstraction. -For an example on best practices for implementing this type of form state management, you can run any of several example implementations with the RADFish CLI: +One downside of this approach is that each form has it's own state management. This can lead to less DRY code. This is an acceptable tradeoff in most cases, however. If you notice that certain patterns should be shared among different components, you will either need to pass these state values as props to child components, or wrap the related components in a `ContextProvider` and expose them via the `useContext` hook. See more about how to use React Context [here](https://react.dev/reference/react/useContext). + +For an example on best practices for implementing this type of form state management, you can run an example implementation with the RADFish CLI: `npx @nmfs-radfish/create-radfish-app my-app --example computed-form-fields` -Below is a simplified code snippet on how to set this form state management up in a React component: +Here is a simplified code snippet on how to set this form state management up in a React component: ```jsx const SimplifiedForm = () => { @@ -66,22 +67,22 @@ const SimplifiedForm = () => { }; ``` -**_Flexibility and Debugging:_** +### Flexibility and Debugging -This method allows developers to implement form state within the scope of a single file, making it simpler to build out forms for different use cases. If certain repeatable patterns arise, they can be broken out into a separate context provider if needed, or alternatively get passed in as props to child components. +This method allows developers to implement form state within the scope of a single file. This makes it simpler to build out forms for different use cases. If certain repeatable patterns arise, they can be broken out into a separate context provider if needed. Alternatively, they can get passed in as props to child components. -This approach provides better encapsulation and modularity, allowing for more straightforward debugging and maintenance of form-related logic. +This approach provides better encapsulation and modularity. It also allows for more straightforward debugging and maintenance of form-related logic. -# Offline / Online State Management +## Offline / Online State Management -A key consideration for any NOAA application, is for it to be able to be fully functional offline without a network connection. Fishermen are often on ships far away from network connection, and need to reliably store data to be uploaded to NOAA services when the app comes back online. For this reason, building with “offline first” considerations is of vital importance to NOAA web application development. +Any NOAA web application must be fully functional offline without a network connection. Fishermen are often on ships far away from network connection. They need to reliably store data that will be uploaded to NOAA services when the app comes back online. Therefore, designing apps to be “offline first” is of vital importance to NOAA web appdevelopment. -Progressive Web Applications (or PWAs) offer a robust solution for offline use at sea, by combining the benefits of a familiar app-like experience, offline access, and efficient data management. These features make PWAs well-suited for maritime environments, where connectivity is often limited or intermittent. +Progressive Web Applications (PWAs) offer a robust solution for offline use at sea. They combine the benefits of an app-like experience, offline access, and efficient data management. These features make PWAs well-suited for maritime environments, where connectivity is often limited or intermittent. -PWAs leverage service workers, which are scripts that run in the background independantly of the main application. Service workers enable offline functionality by caching important static resources, such as HTML, CSS, and JavaScript files. This allows the PWA to continue functioning event when there’s no network connectivity. +PWAs leverage service workers, which are scripts that run independently in the background. Service workers enable offline functionality by caching important static resources, such as HTML, CSS, and JavaScript files. This allows the PWA to continue functioning even when there’s no network connectivity. -**See more about service workers [here](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)**. +Read more about service workers [here](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API). Service workers are integrated into the RADFish application by default. After scaffolding the application you will notice the following files: @@ -102,9 +103,9 @@ This will register the React application as a PWA, which can be downloaded from Additionally, you can query for whether or not the RADFish application is online or offline by leveraging the [navigator API](https://developer.mozilla.org/en-US/docs/Web/API/Navigator). -> Note, that this service worker is preconfigured when using the boilerplate `react-javascript` template +> Note: This service worker is preconfigured when using the boilerplate `react-javascript` template. -It is up to the developer on how, or where this API needs to be used, but it is a good idea to use it early on in your application, so that the rest of the application can listen for changes in offline state. The `@nmfs-radfish/react-radfish` package exposes a `useOfflineStatus` hook that allows you a simple way to tap into whether or not your application is online: +It is up to the developer on how or where this API needs to be used. It's a good idea to use it early on in your application, so that the rest of the application can listen for changes in offline state. The `@nmfs-radfish/react-radfish` package exposes a `useOfflineStatus` hook that gives you a simple way to tap into whether or not your application is online: ```jsx import { Application, useOfflineStatus } from "@nmfs-radfish/react-radfish"; @@ -122,27 +123,27 @@ function App() { } ``` -This underlying code listens for changes surfaced from the `navigator` API, and notifies the application in the form of a Toast message of the applications online/offline state. +This underlying code listens for changes surfaced from the `navigator` API. It notifies the application in the form of a Toast message of the application's online/offline state. -> 🚨 Warning: Note that there is a known issue, where if the user's device is in an offline state, and the RADFish application is booted up for the first time, the Navigator API will actually resolve to "offline". On future refreshes, this will appropriately resolve to the "offline" status. This is an issue with the underlying Navigator API and will be addressed in a future release. +> 🚨 **Warning:** There is a known issue where if the user's device is in an offline state, and the RADFish application is booted up for the first time, the Navigator API will actually resolve to "offline". On future refreshes, this will appropriately resolve to the "offline" status. This is an issue with the underlying Navigator API and will be addressed in a future release. -## **Caching Strategy** +## Caching Strategy It is important to fetch and cache required data needed to basic app functionality while the application is online. This can be done by fetching the required data from an API, and storing that data into IndexedDB. To see a basic example of how this can be done, you can run the `server-sync` example from the CLI: `npx @nmfs-radfish/create-radfish-app my-app --example server-sync` -This example fetches several JSON arrays from our Mock API, then stores and caches it in IndexedDB. The application then can reference the data in IndexedDB without needing to have any network connection. Keep in mind that it is up to the developer to decide when and how to invalidate this IndexedDB cache in according to their application's needs. +This example fetches several JSON arrays from our Mock API, then stores and caches it in IndexedDB. The application then can reference the data in IndexedDB without a network connection. Keep in mind that it is up to the developer to decide when and how to invalidate this IndexedDB cache based on their application's needs. ## **Offline Storage** -To use offline data storage, use the `useOfflineStorage` hook. This React hook provides methods for managing offline form data. There are two storage methods available `LocalStorageMethod` or `IndexedDBStorageMethod`. +To use offline data storage, use the `useOfflineStorage` hook. This React hook provides methods for managing offline form data. There are two storage methods available: `LocalStorageMethod` and `IndexedDBStorageMethod`. ### Configuration Step-by-step instructions to configure offline storage: -1. **Set the environment variables in the `.env` files. Based on which offline storage method you select, the following env variables are required:** +1. **Set the environment variables in the `.env` files. Based on which offline storage method you select, the following `env` variables are required:** 1. Local Storage 1. `VITE_LOCAL_STORAGE_KEY` 2. Indexed DB: @@ -150,7 +151,7 @@ Step-by-step instructions to configure offline storage: 2. `VITE_INDEXED_DB_VERSION` 3. `VITE_INDEXED_DB_TABLE_NAME` 4. `VITE_INDEXED_DB_SCHEMA` -2. **In the `src/hooks/useOfflineStorage.js` file, initialize one of the following Storage Method instances, and pass the appropriate environment variables using `import.meta.env.REPLACE_WITH_KEY_NAME` as parameters:** +2. **In the `src/hooks/useOfflineStorage.js` file, initialize one of the these Storage Method instances, and pass the appropriate environment variables using `import.meta.env.REPLACE_WITH_KEY_NAME` as parameters:** 1. `LocalStorageMethod` — Requires one parameter, the key name for localStorage. @@ -171,7 +172,7 @@ Step-by-step instructions to configure offline storage: ); ``` -3. **In the `src/hooks/useOfflineStorage.js` file, create the `StorageModelFactory` :** +3. **In the `src/hooks/useOfflineStorage.js` file, create the `StorageModelFactory`:** ```jsx // 1. Choose one of the following storage methods: @@ -188,24 +189,24 @@ Step-by-step instructions to configure offline storage: const storageModel = StorageModelFactory.createModel(storageMethod); ``` -### **`useOfflineStorage` Hooks API** +### `useOfflineStorage` Hooks API The `useOfflineStorage` hook returns an object with the following methods: -- **`createOfflineDataEntry(data)` —** Creates a new data entry in the storage. +- **`createOfflineDataEntry(data)`** creates a new data entry in the storage. - `data`: The data object to create. - Returns a promise that resolves when the data is created. -- **`findOfflineData(criteria)`** — Finds data in the storage based on the given criteria, returns all data if not criteria parameter is passed. +- **`findOfflineData(criteria)`** finds data in the storage based on the given criteria. It returns all data if not criteria parameter is passed. - `criteria`: The criteria object to use for finding data, eg `{uuid: 123}`. - Returns a promise that resolves to an array of tuples: - `[ [ uuid, { key: value } ], [ uuid2, { key: value } ] ]` -- **`updateOfflineDataEntry(criteria, data)`** — Updates data in the storage. +- **`updateOfflineDataEntry(criteria, data)`** updates data in the storage. - `criteria`: The criteria to use for updating data. This should be an object. - `data`: The updated data object. - Returns a promise that resolves to the updated data as an object: - `{ numberOfFish: 10, species: salmon }` -### **Usage** +### Usage ```jsx import useOfflineStorage from "./useOfflineStorage"; @@ -232,11 +233,11 @@ export default MyComponent; --- -# OfflineStorageWrapper Usage Guide +## OfflineStorageWrapper Usage Guide `OfflineStorageWrapper` is a context wrapper component that provides offline storage functionality to its child components through a React context. It supports both IndexedDB and LocalStorage methods. -## How to Use +### How to Use **1. Wrap your component with `OfflineStorageWrapper`:** @@ -250,7 +251,7 @@ import { OfflineStorageWrapper } from "@nmfs-radfish/react-radfish"; The config prop is an object that specifies the storage type and configuration. It should include the `type` set to `indexedDB` or `localStorage`, database name (`string`), database version number (`number`), and stores (`object`). -The `stores` object should contain a key that is mapped as the table name, the value should be a comma separated string that outlines the schema. For more information on setting up the stores, please see the official `Dexie.js` docs: [https://dexie.org/docs/Tutorial/React#3-create-a-file-dbjs-or-dbts](https://dexie.org/docs/Tutorial/React#3-create-a-file-dbjs-or-dbts). +The `stores` object should contain a key that is mapped as the table name. The value should be a comma separated string that outlines the schema. For more information on setting up the stores, see the official `Dexie.js` docs: [https://dexie.org/docs/Tutorial/React#3-create-a-file-dbjs-or-dbts](https://dexie.org/docs/Tutorial/React#3-create-a-file-dbjs-or-dbts). For IndexedDB, the configuration should look like this: @@ -305,8 +306,8 @@ If you try to use the `useOfflineStorage` hook outside of an `OfflineStorageWrap ## Testing during development -As a developer, you will often run into an issue where you are developing an "offline-first" feature that needs to be tested before pushed and merged into the `main` branch. For instance, you may be developing a `Toast` message that notifies the user whenever they go offline. If you are simply running the local vite server, and you go offline to test your feature, you'll notice that the page breaks on page refresh. This is because the `serviceWorker` is not being used until the production build is created. In order to do this, you need to bundle the application and serve it locally in order to simulate a production environment: +As a developer, you'll often run into an issue where an "offline-first" feature needs to be tested before pushed and merged into the `main` branch. For instance, you may be developing a `Toast` message that notifies the user whenever they go offline. If you are simply running the local vite server, and you go offline to test your feature, you'll notice that the page breaks on page refresh. This is because the `serviceWorker` is not being used until the production build is created. In order to do this, you need to bundle the application and serve it locally to simulate a production environment: `npm run build && npm run serve` -This will bundle the application and serve it, so that when you turn your browser offline, the cached static assets will remain, and your application will not break when the page is refreshed. +This will bundle the application and serve it. When you turn your browser offline, the cached static assets will remain, and your application will not break when the page is refreshed. From 40e6cf1de7d765172e26a2412aabe88f21a16b65 Mon Sep 17 00:00:00 2001 From: oanelson Date: Mon, 2 Dec 2024 21:31:20 -0800 Subject: [PATCH 3/9] Edits towards 165 --- .../development-life-cycle.md | 8 +-- .../patterns/apiservice.md | 49 +++++++++---------- .../patterns/mock-api.md | 2 +- 3 files changed, 29 insertions(+), 30 deletions(-) diff --git a/docs/developer-documentation/building-your-application/development-life-cycle.md b/docs/developer-documentation/building-your-application/development-life-cycle.md index c7392fb..a54718b 100644 --- a/docs/developer-documentation/building-your-application/development-life-cycle.md +++ b/docs/developer-documentation/building-your-application/development-life-cycle.md @@ -18,9 +18,9 @@ To setup a new NOAA web app project, we recommend following [Getting Started](.. ## React Components -The following components are included by default with the RADFish Framework. The components build upon the ‣ component library, which adheres to [USWDS standards](https://designsystem.digital.gov/). For detailed information on the available components and what attributes they accept, please see the official storybook documentation: [https://trussworks.github.io/react-uswds/](https://trussworks.github.io/react-uswds/) +Trussworks React components are included by default with the RADFish Framework. The components build upon the component library, which adheres to [USWDS standards](https://designsystem.digital.gov/). For detailed information on the available components and what attributes they accept, please see the official storybook documentation: [https://trussworks.github.io/react-uswds/](https://trussworks.github.io/react-uswds/) -###Why Use React? +### Why Use React? - **Responsive Design.** Automatically adjusts for different screen sizes with a collapsible menu. - **Customizable.** Allows for easy customization of navigation links. @@ -29,10 +29,10 @@ The following components are included by default with the RADFish Framework. The **Additional Notes** -- The **`@trussworks/react-uswds`** package is a requirement for this component to ensure proper styling and functionality. This package is included by default. +- The **`@trussworks/react-uswds`** package is required to ensure proper styling and functionality. This package is included by default, so you do not need to import it. - Custom CSS can be applied for further customization. -##Resources +## Resources By integrating the [header](https://trussworks.github.io/react-uswds/?path=/docs/components-header--basic-header) components into your React application, you can create a professional and responsive UI with minimal effort. The **`Layout`** and **`HeaderNav`** components work together to provide a structured and navigable interface, enhancing the overall user experience. diff --git a/docs/developer-documentation/building-your-application/patterns/apiservice.md b/docs/developer-documentation/building-your-application/patterns/apiservice.md index 0904edb..45f4fed 100644 --- a/docs/developer-documentation/building-your-application/patterns/apiservice.md +++ b/docs/developer-documentation/building-your-application/patterns/apiservice.md @@ -5,11 +5,11 @@ description: Use any network library to handle HTTP requests # Integrating with Backend Services -You are free to use any network library of your choice to handle HTTP requests (GET, POST, PUT, DELETE). For your convenience, we’ve provided examples using the native fetch API. You can adapt these examples to the library that best fits your needs. +You can use any network library to handle HTTP requests (GET, POST, PUT, DELETE). We’ve provided examples using the native fetch API. You can adapt these examples to the library that best fits your needs. -**Making API Requests** +## Making API Requests -A common pattern, is to call network requests in a `useEffect` that will trigger whenever a React component loads: +A common pattern is to call network requests in a `useEffect` that will trigger whenever a React component loads: ```jsx useEffect(() => { @@ -34,12 +34,11 @@ useEffect(() => { }, []); ``` -- **`GET` Request** - - - Asynchronous function to perform a `GET` request - - `@param {string} endpoint` - The API endpoint to perform the GET request. - - `@param {Object} queryParams` - The query parameters for the GET request. - - `@returns {Promise}` - A promise that resolves to the API response data or an error string. +### `GET` Request +Asynchronous function to perform a `GET` request. +- `@param {string} endpoint` - The API endpoint to perform the GET request. +- `@param {Object} queryParams` - The query parameters for the GET request. +- `@returns {Promise}` - A promise that resolves to the API response data or an error string. ```js async function get(API_ENDPOINT, queryParams) { @@ -76,12 +75,12 @@ useEffect(() => { }, []); ``` -- **`POST` Request** +### `POST` Request - - Asynchronous function to perform a `POST` request - - `@param {string} endpoint` - The API endpoint to perform the POST request. - - `@param {Object} body` - The request body for the POST request. - - `@returns {Promise}` - A promise that resolves to the API response data or an error string. +Asynchronous function to perform a `POST` request. +- `@param {string} endpoint` - The API endpoint to perform the POST request. +- `@param {Object} body` - The request body for the POST request. +- `@returns {Promise}` - A promise that resolves to the API response data or an error string. ```jsx async function post(API_ENDPOINT, bodyData) { @@ -119,12 +118,12 @@ useEffect(() => { }, []); ``` -- **`PUT` Request** +### `PUT` Request - - Asynchronous function to perform a `PUT` request - - `@param {string} endpoint` - The API endpoint to perform the PUT request. - - `@param {Object} body` - The request body for the PUT request. - - `@returns {Promise}` - A promise that resolves to the API response data or an error string. +Asynchronous function to perform a `PUT` request. +- `@param {string} endpoint` - The API endpoint to perform the PUT request. +- `@param {Object} body` - The request body for the PUT request. +- `@returns {Promise}` - A promise that resolves to the API response data or an error string. ```jsx async function update(endpoint, { id, bodyData }) { @@ -168,12 +167,12 @@ useEffect(() => { }, []); ``` -- **`DELETE` Request** +### `DELETE` Request - - Asynchronous function to perform a `DELETE` request - - `@param {string} endpoint` - The API endpoint to perform the DELETE request. - - `@param {Object} body` - The request body for the DELETE request. - - `@returns {Promise}` - A promise that resolves to the API response data or an error string. +Asynchronous function to perform a `DELETE` request. +- `@param {string} endpoint` - The API endpoint to perform the DELETE request. +- `@param {Object} body` - The request body for the DELETE request. +- `@returns {Promise}` - A promise that resolves to the API response data or an error string. ```jsx async function remove(endpoint, { id }) { @@ -210,6 +209,6 @@ useEffect(() => { ``` --- -# React Query +## React Query In Progress diff --git a/docs/developer-documentation/building-your-application/patterns/mock-api.md b/docs/developer-documentation/building-your-application/patterns/mock-api.md index bb89561..b72bf6a 100644 --- a/docs/developer-documentation/building-your-application/patterns/mock-api.md +++ b/docs/developer-documentation/building-your-application/patterns/mock-api.md @@ -5,7 +5,7 @@ description: Simulate backend responses to unblock your development # Mock API -As a frontend developer, it can sometimes be a blocker when you are developing a feature that has a dependency on an external API. Often times, you can be waiting for a backend developer to finish building our their API endpoints before you can continue building your feature. RADFishApp ships with a built-in mock server that allows the frontend developer to “stub out” and mock API requests/responses without this hard dependency during development. +As a frontend developer, you may be developing a feature that has a dependency on an external API. This dependency sometimes becomes a blocker. You must wait for the external API endpoints to be developed before you can build your feature. The RADFish app ships with a built-in mock server that allows frontend developers to “stub out” and mock API requests. This mock API removes the hard dependency during development. More specifically, RADFishApp ships with [mock service worker](https://mswjs.io/) and is preconfigured in the boilerplate application. From 2b6540bf4be143fd1a4cdae5a5653398125a4e11 Mon Sep 17 00:00:00 2001 From: oanelson Date: Tue, 3 Dec 2024 22:53:05 -0800 Subject: [PATCH 4/9] progress on 165 --- .../patterns/components.md | 34 +++++++++---------- .../patterns/mock-api.md | 10 +++--- .../patterns/navigation.md | 32 ++++++++--------- 3 files changed, 37 insertions(+), 39 deletions(-) diff --git a/docs/developer-documentation/building-your-application/patterns/components.md b/docs/developer-documentation/building-your-application/patterns/components.md index 2c2287a..87ab5be 100644 --- a/docs/developer-documentation/building-your-application/patterns/components.md +++ b/docs/developer-documentation/building-your-application/patterns/components.md @@ -7,13 +7,11 @@ description: Learn to build and structure your components ## Building your first page and form -When building applications with React, there is an existing component library, [react-uswds](https://trussworks.github.io/react-uswds/?path=/docs/welcome--docs) that our project extends for the purposes of building any RADFish application. These components maintain all functionality of `react-uswds` components, but are branded with NOAA themes and styles. These components live in `react-radfish` directory, and allow for development in a modern React environment with NOAA look and feel. +RADFish uses standard components from the [`react-uswds`](https://github.com/trussworks/react-uswds) open source project. The RADFish project further extends the react-uswds library. These components maintain the functionality of react-uswds, but are branded with NOAA themes and styles. These components live in the [`react-radfish` directory](https://github.com/NMFS-RADFish/react-components). This allows for development in a modern React environment with a NOAA look and feel. -For reference on the full `react-uswds` library, you can reference the deployed storybook: +For more information on the full `react-uswds` library, check out the deployed storybook: [https://trussworks.github.io/react-uswds/](https://trussworks.github.io/react-uswds/?path=/docs/welcome--docs) -[https://trussworks.github.io/react-uswds/](https://trussworks.github.io/react-uswds/?path=/docs/welcome--docs) - -**Example** +### Example If you wanted to build a `TextInput` component into an existing form, you can use the `@trussworks` [storybook reference](https://trussworks.github.io/react-uswds/?path=/docs/components-text-input--docs) related to component props that are available. @@ -37,30 +35,30 @@ import { TextInput, Label } from "@trussworks/react-uswds"; ### Forms -Controlled forms are a key aspect of any NOAA application, and is used to collect data relevant to that application in the context of the user. This could be intaking data related to trip reports, admin applications, or similar types of scope. +Controlled forms are a key aspect of any NOAA application. Forms are used to collect data relevant to that application in the context of the user. For example, forms can intake data related to trip reports or admin applications. -For more specific information regarding how to build a form, you can reference the [State Management](./state-management.md) portion of this documentation. +To learn how to build a form, refer to the [State Management](./state-management.md) documentation. ### Tables -Tables are also a key component type for all NOAA applications. These components are usually meant for visualizing data in a user friendly manner. However, there are cases where having this data also be writable (ie: submittable) to a backend. Utilizing caching strategies with IndexedDB is an effective way to ensure that these types of components remain fully functional when offline. +Tables are also a key component type for all NOAA applications. These components usually help visualize data in a user-friendly manner. However, there are cases where developers may want this data to be writable (ie: submittable) to a backend. Using caching strategies with IndexedDB ensures that these types of components remain fully functional when offline. -For more specific information regarding how to build a table, you can reference the [State Management](./state-management.md) portion of this documentation. +To learn how to build a table, refer to the [State Management](./state-management.md) documentation. ## Styling Methodology: BEM -In our **examples** and **templates**, we follow the **BEM (Block Element Modifier)** methodology for organizing CSS classes. BEM helps create a structured and scalable CSS architecture, making it easier to understand where CSS classes belong and how they relate to components. It also promotes consistency and readability, especially in larger codebases. +In our **examples** and **templates**, we follow the **Block Element Modifier (BEM)** methodology for organizing CSS classes. BEM helps create a structured and scalable CSS architecture. This makes it easier to understand where CSS classes belong and how they relate to components. It also promotes consistency and readability, especially in larger codebases. -For more information on BEM and how it works, you can visit the official BEM documentation: [https://getbem.com](https://getbem.com). +We use BEM for other reasons as well: -### Why We Use BEM: +- **Clarity.** BEM conventions make it clear how styles are applied across different parts of a component. +- **Modularity.** BEM encourages the separation of styling concerns, making components more modular and reusable. +- **Scalability.** As your project grows, BEM helps maintain organized and manageable CSS. -- **Clarity**: BEM conventions make it clear how styles are applied across different parts of a component. -- **Modularity**: It encourages the separation of styling concerns, making components more modular and reusable. -- **Scalability**: As your project grows, BEM helps maintain organized and manageable CSS. +For more information on BEM and how it works, you can visit the official BEM documentation: [https://getbem.com](https://getbem.com). -#### Flexibility for Your Project: +### Flexibility for Your Project: -While we use BEM in our **examples** and **templates** to enhance code clarity and consistency, you are not required to adopt BEM in your own project. Feel free to use any CSS methodology or framework that suits your needs, whether it’s **BEM**, **CSS Modules**, **Tailwind**, or any other approach. +We use BEM in our **examples** and **templates** to enhance code clarity and consistency. However, you are not required to adopt BEM in your own project. Feel free to use any CSS methodology or framework that suits your needs. This might be BEM, CSS Modules, Tailwind, or any other approach. -Our use of BEM is limited to the examples and templates provided, so it won’t affect how you structure your own styles. You can implement your own styling approach while still benefiting from the components and patterns showcased in our examples. +Our use of BEM is limited to the examples and templates provided. It doesn’t affect how you structure your own styles. You can implement your own styling approach while using the components in our examples. diff --git a/docs/developer-documentation/building-your-application/patterns/mock-api.md b/docs/developer-documentation/building-your-application/patterns/mock-api.md index b72bf6a..46ccd40 100644 --- a/docs/developer-documentation/building-your-application/patterns/mock-api.md +++ b/docs/developer-documentation/building-your-application/patterns/mock-api.md @@ -7,7 +7,7 @@ description: Simulate backend responses to unblock your development As a frontend developer, you may be developing a feature that has a dependency on an external API. This dependency sometimes becomes a blocker. You must wait for the external API endpoints to be developed before you can build your feature. The RADFish app ships with a built-in mock server that allows frontend developers to “stub out” and mock API requests. This mock API removes the hard dependency during development. -More specifically, RADFishApp ships with [mock service worker](https://mswjs.io/) and is preconfigured in the boilerplate application. +More specifically, RADFish ships with [mock service worker](https://mswjs.io/). This service is preconfigured in the boilerplate application. At the entrypoint of the React application, we enable API mocking with the `enableMocking` function: @@ -31,11 +31,11 @@ enableMocking().then(() => { }); ``` -Keep in mind that mocking should only be available during development, and should not ship with the production application. It can be useful to use a `NODE_ENV` environment variable to ensure that API mocks are only used in `DEVELOPMENT`. The `public/mockServiceWorker.js` file installs and configures the mock server. You should not need to modify this file. +Keep in mind that mocking should only be available during development. It should not ship with the production application. It can be useful to use a `NODE_ENV` environment variable to ensure that API mocks are only used in `DEVELOPMENT`. The `public/mockServiceWorker.js` file installs and configures the mock server. You should not need to modify this file. -**Configuring mock endpoints:** +## Configuring mock endpoints: -In `src/mocks` you will notice a `browser.js` file and a `handlers.js` file. As a developer, you will do most of your work in `handlers.js` file, where you can add different mock http handlers to your application. For each handler you create, the mock service worker will intercept the request, and handle that request as defined in the file. +In `src/mocks` there is a `browser.js` file and a `handlers.js` file. Developers can add different mock http handlers to their application in the `handlers.js` file. For each handler you create, the mock service worker will intercept the request, and handle that request as defined in the file. For instance: @@ -51,6 +51,6 @@ export const handlers = [ ]; ``` -This file creates two handlers, a `GET` and `POST` request that returns a `HttpResponse` to the application. We recommend looking at the [msw docs](https://mswjs.io/) for more detailed information on how to further customize this for your needs. +This file creates two handlers, a `GET` and `POST` request that returns a `HttpResponse` to the application. Refer to the [msw docs](https://mswjs.io/) for more information on customizing this for your needs. --- diff --git a/docs/developer-documentation/building-your-application/patterns/navigation.md b/docs/developer-documentation/building-your-application/patterns/navigation.md index 141c046..bcb38f1 100644 --- a/docs/developer-documentation/building-your-application/patterns/navigation.md +++ b/docs/developer-documentation/building-your-application/patterns/navigation.md @@ -5,29 +5,29 @@ description: Handle navigation patterns in your application # Navigation -A NOAA application can often have various, application specific needs for routing and navigation between internal pages. It may also need to follow certain domain specific rules when needed (ie, be hosted on a subdomain route of an existing application). For the purposes of this documentation, we will focus primarily on the situation where an application is hosted on it’s own domain, and from the root directory of that application’s codebase. +NOAA applications often have application-specific needs for routing and navigation between internal pages. They may also need to follow certain domain-specific rules, such as being hosted on a subdomain route of an existing application. In this documentation, we'll focus on applications that are on hosted on their own domain, and from the root directory of that application’s codebase. -It is important for NOAA to maintain a similar navigation style between it’s collection of applications in order to provide a familiar interface for users that may be switching between applications. Styles of navigation elements should be consistent across various platforms, and each application should have at the bare minimum, routes to the suggested pages that the USWDS guidelines suggest in the [templates](https://designsystem.digital.gov/templates/) portion of their Design System Documentation. This will allow a foundational application structure that is both repeatable and familiar to users. +## Navigation Styling +NOAA applications should maintain a similar navigation style. This provides a familiar interface for users who may be switching between applications. Navigation element styles should be consistent across various platforms. -Generally speaking, navigation items should always be at the highest vertical “layer” of the application, and should always overlap any other components, with exception of full page modals. For instance, if a navigation item expands downwards, it should not be layered beneath a hero image or some other component. This would make the Navigation inaccessible and not comply with 508 compliance regulations. +Navigation items should always be at the highest vertical “layer” of the application. They should always overlap any other components, except for full page modals. For example, if a navigation item expands downwards, it should not appear beneath an image or some other component. This would make the navigation inaccessible and not comply with 508 compliance regulations. -Navigation should also appear different on both mobile and desktop/tablet devices. +Navigation should also appear different on mobile and desktop/tablet devices. -### Application Routing +## Application Routing +In Progressive Web App (PWA) development, application routing provides a seamless user experience. The implementation of application routing can vary based on business needs. However, there are general principles that developers can follow to ensure a consistent and user-friendly navigation experience. -In the context of Progressive Web App (PWA) development, application routing plays a crucial role in providing users with a seamless and engaging experience. The implementation of application routing can vary based on business needs, but there are general principles and expected patterns that developers follow to ensure a consistent and user-friendly navigation experience. +NOAA applications should have routes to the pages suggested in the [templates](https://designsystem.digital.gov/templates/) portion of the USWDS documentation. This creates an application structure that is both repeatable and familiar to users. -The U.S. Web Design System (USWDS) documentation provides valuable insights into recommended basic routes for a PWA application. These routes include: +The U.S. Web Design System (USWDS) documentation provides recommended basic routes for a PWA application. These routes include: -1. **404 Page:** Handling page not found scenarios gracefully is essential for user satisfaction. A well-designed 404 page helps users understand that the content they are looking for is not available. -2. **Documentation Page:** Including a dedicated page for documentation can enhance user understanding of the application's features and functionality. This page serves as a reference guide for users seeking information about how to use the app effectively. -3. **Landing Page:** The landing page is often the first interaction users have with the application. It should be designed to capture attention, provide key information, and encourage users to explore further. -4. **Authentication Page:** Secure authentication is a critical aspect of many applications. Having a dedicated authentication page ensures a smooth and secure login process for users. +- **404 Page.** Handling "page not found" scenarios gracefully is essential for user satisfaction. A well-designed 404 page helps users understand that the content they're looking for is not available. +- **Documentation Page.** Including documentation can help users understand the application's features and functionality. This page serves as a reference guide for users seeking information about how to use the app effectively. +- **Landing Page.** The landing page is often the first interaction users have with the application. It should be designed to capture attention, provide key information, and encourage users to explore further. +- **Authentication Page.** Secure authentication is a critical aspect of many applications. Having a dedicated authentication page ensures a smooth and secure login process for users. -In addition, offline functionality is a key consideration. The application should be designed to work seamlessly even when the user is offline. To address this, the routing mechanism should direct users to a page that doesn't depend on external API requests and relies solely on cached content. +NOAA applications should be designed to work seamlessly even when the user is offline. The routing mechanism should direct users to a page that doesn't depend on external API requests. It should rely solely on cached content. -Referencing the "online usage" portion of the developer documentation is crucial for understanding how the application behaves when the user is offline. This documentation typically outlines strategies for caching important assets, handling offline scenarios, and ensuring that users can still access meaningful content even without an internet connection. +The "online usage" documentation explains how the application behaves when the user is offline. This documentation typically outlines strategies for caching important assets, handling offline scenarios, and ensuring that users can still access content even without an internet connection. -In summary, effective application routing in PWA development involves careful consideration of key routes such as 404, documentation, landing, and authentication pages. Additionally, prioritizing offline use by routing to cached content during periods of no internet connectivity enhances the overall user experience. Developers should follow best practices and refer to relevant documentation to implement routing that aligns with both business needs and user expectations. - ---- +In summary, effective application routing in PWA development involves careful consideration of key routes such as 404, documentation, landing, and authentication pages. Additionally, prioritizing offline use by routing to cached content enhances user experience. Developers should follow best practices and refer to relevant documentation to implement routing that aligns with both business needs and user expectations. From b8e694f021fc683b32fcbdf36d9fcb22e5bd9bec Mon Sep 17 00:00:00 2001 From: oanelson Date: Wed, 4 Dec 2024 16:56:24 -0800 Subject: [PATCH 5/9] Progress on 165 --- .../patterns/debugging.md | 12 +-- .../patterns/offline-storage.md | 22 ++++-- .../patterns/routing.md | 20 ++--- .../patterns/testing.md | 77 ++++++++++--------- 4 files changed, 70 insertions(+), 61 deletions(-) diff --git a/docs/developer-documentation/building-your-application/patterns/debugging.md b/docs/developer-documentation/building-your-application/patterns/debugging.md index 5ad0387..212a7d9 100644 --- a/docs/developer-documentation/building-your-application/patterns/debugging.md +++ b/docs/developer-documentation/building-your-application/patterns/debugging.md @@ -5,13 +5,13 @@ description: Strategies for debugging your applications # Debugging -Debugging plays pivotal roles in the development of Progressive Web Applications (PWAs) by enabling developers to track real-time performance, identify/fix bugs, optimize code, and enhance overall user experience. +Debugging is an important part developing Progressive Web Applications (PWAs). Debugging helps developers track real-time performance, identify and fix bugs, optimize code, and enhance user experience. There are several common strategies for debugging a web application during development. These include but are not limited to: -- Adding breakpoints in code editor: [See vscode documentation](https://code.visualstudio.com/docs/editor/debugging#_breakpoints) -- Adding logs to the development console: [See MDN documentation](https://developer.mozilla.org/en-US/blog/learn-javascript-console-methods/) -- Using the network console: [See Chrome DevTools documentation](https://developer.chrome.com/docs/devtools/network) -- Using an HTTP client like Postman to test API calls: [See Postman documentation](https://learning.postman.com/docs/introduction/overview/) +- Adding breakpoints in code editor. [See vscode documentation](https://code.visualstudio.com/docs/editor/debugging#_breakpoints). +- Adding logs to the development console. [See MDN documentation](https://developer.mozilla.org/en-US/blog/learn-javascript-console-methods/). +- Using the network console. [See Chrome DevTools documentation](https://developer.chrome.com/docs/devtools/network). +- Using an HTTP client like Postman to test API calls. [See Postman documentation](https://learning.postman.com/docs/introduction/overview/). -Note that you can use postman in conjunction with the Mock Service Worker that is bundled with RadFish in order to emulate a backend server response pattern. +You can use Postman to emulate a backend server response pattern. Postman works with the Mock Service Worker that is bundled with RadFish. diff --git a/docs/developer-documentation/building-your-application/patterns/offline-storage.md b/docs/developer-documentation/building-your-application/patterns/offline-storage.md index 8ffdef5..86b9529 100644 --- a/docs/developer-documentation/building-your-application/patterns/offline-storage.md +++ b/docs/developer-documentation/building-your-application/patterns/offline-storage.md @@ -6,7 +6,7 @@ description: Implement offline storage functionality (Coming soon) # Offline Storage -RADFish application users can be out at sea for an extended period of time and may not have a reliable internet connection. The offline storage functionality outlined below allows users to continue using the application to create and manage data while offline. +RADFish app users can be out at sea for an extended period of time. They may not have a reliable internet connection. Offline storage lets users to continue using the app to create and manage data while offline. ## Storage Models @@ -26,7 +26,7 @@ new LocalStorageMethod( ### IndexedDB -When using IndexedDB, we additionally need to provide a schema version and model structures. These are used to manage future data migrations. +When using IndexedDB, we also need to provide a schema version and model structures. These are used to manage future data migrations. ```js import { IndexedDBStorageMethod } from '@nmfs-radfish/radfish'; @@ -43,13 +43,17 @@ new IndexedDBStorageMethod( ## React Usage -The `@nmfs-radfish/react-radfish` package exposes the an `OfflineStorageWrapper` component that creates a storage model available to that React context. +The `@nmfs-radfish/react-radfish` package exposes the `OfflineStorageWrapper` component. This creates a storage model available to that React context. ## **`useOfflineStorage` Hooks API** You can then use the `useOfflineStorage` hook to interact directly with the storage model. -The hook returns an object with the following methods: +The hook returns an object with these CRUD methods: +- `createOfflineData` creates a new entry. +- `findOfflineData` reads data entries. +- `updateOfflineData` updates data entries. +- `deleteOfflineData` deletes data entries. ### `createOfflineData` @@ -86,7 +90,7 @@ Updates data in the storage with the matching `criteria`. ### `deleteOfflineData` - Deletes data in the storage. +Deletes data in the storage. | Parameter | Description | | ----------- | -------------------------------------------------------------- | @@ -95,11 +99,11 @@ Updates data in the storage with the matching `criteria`. **Returns:** A `Promise` that resolves to a boolean value of whether the delete operation succeeded without errors. -## **Usage** +## Usage Example usage when using IndexedDB: -App.jsx +**App.jsx** ```jsx import React, { useEffect, useState } from "react"; import { Table } from "@nmfs-radfish/react-radfish"; @@ -162,4 +166,6 @@ export default App; ## Interfacing with backend services -You can use any HTTP library of your choice to handle HTTP requests (GET, POST, PUT, DELETE). For your convenience, we’ve provided examples using the native fetch API. You can adapt these examples to the library that best fits your needs. +You are free to use any network library of your choice to handle HTTP requests (GET, POST, PUT, DELETE). For your convenience, we’ve provided examples using the native fetch API. You can adapt these examples to the library that best fits your needs. + +Refer to the [Integrating with Backend Services](https://nmfs-radfish.github.io/radfish/developer-documentation/building-your-application/patterns/apiservice) documentation for examples. diff --git a/docs/developer-documentation/building-your-application/patterns/routing.md b/docs/developer-documentation/building-your-application/patterns/routing.md index b25217a..c564695 100644 --- a/docs/developer-documentation/building-your-application/patterns/routing.md +++ b/docs/developer-documentation/building-your-application/patterns/routing.md @@ -5,24 +5,24 @@ description: Manage app routes with React Router # Routing -The **Routing** in this application is handled using `react-router-dom`, a powerful library for routing in React applications. This section will guide you through the basic setup and usage of routing in your project. +The **Routing** in RADFish applications is handled using `react-router-dom`. This section will guide you through the basic setup and usage of routing in your project. -### **React Router Overview** +## React Router Overview React Router provides a declarative, component-based approach to defining routes and managing navigation in React applications. It supports nested routes, dynamic route matching, and lazy loading of components. -For detailed documentation on React Router, please refer to the official [React Router documentation](https://reactrouter.com/). +To learn about React Router, refer to the official [React Router documentation](https://reactrouter.com/). -### **Features** +### Features -- **Declarative Routing**: Define routes in a declarative manner using components like `Routes`, `Route`, and `Link`. -- **Dynamic Routing**: Easily create routes that can change based on the application's state or URL parameters. -- **Nested Routing**: Support for nested routes, allowing more complex routing configurations. -- **Programmatic Navigation**: Use React Router hooks like `useNavigate` to navigate programmatically. +- **Declarative Routing.** Define routes in a declarative manner using components like `Routes`, `Route`, and `Link`. +- **Dynamic Routing.** Easily create routes that can change based on the application's state or URL parameters. +- **Nested Routing.** Support for nested routes, allowing more complex routing configurations. +- **Programmatic Navigation.** Use React Router hooks like `useNavigate` to navigate programmatically. -### **Usage** +### Usage -In this project, routing is set up in the `App.jsx` file. Below is a breakdown of the main components used for routing: +In this project, routing is set up in the `App.jsx` file. This section provides a breakdown of the main components used for routing. **Basic Setup** diff --git a/docs/developer-documentation/building-your-application/patterns/testing.md b/docs/developer-documentation/building-your-application/patterns/testing.md index 0984ad6..e47d416 100644 --- a/docs/developer-documentation/building-your-application/patterns/testing.md +++ b/docs/developer-documentation/building-your-application/patterns/testing.md @@ -5,17 +5,23 @@ description: Ensure code quality with Vitest and React Testing Library # Testing -Testing is a critical part of the software development process, ensuring the reliability and maintainability of your React application. This section provides an overview of writing tests using [Vitest](https://vitest.dev/api/), along with additional frameworks like [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) for different types of tests: snapshot, unit, and browser testing. This section also covers debugging techniques for broken or failed tests and best practices for effective test writing. +Testing is a critical part of the software development process. Testing ensures the reliability and maintainability of your React application. This section provides an overview of several topics: +- Writing tests using [Vitest](https://vitest.dev/api/) +- Snapshot, unit, and browser testing with frameworks like [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) +- Debugging techniques for broken or failed tests +- Best practices for effective test writing -## **Running Tests** +Effective testing in React using Vitest and related frameworks builds robust applications. Remember, the goal of testing is not just to find bugs, but to build confidence in your codebase. + +## Running Tests Run tests with the following command: `npm test` -## **Writing Unit Tests** +## Writing Unit Tests Unit tests focus on testing individual components or functions in isolation. -1. **Basic Unit Test**: +1. **Basic Unit Test** ```jsx import { @@ -32,9 +38,9 @@ Unit tests focus on testing individual components or functions in isolation. }); ``` -2. **Testing User Interactions**: +2. **Testing User Interactions** - Utilize **`user-event`** or **`fireEvent`** from React Testing Library to simulate user actions. +Use **`user-event`** or **`fireEvent`** from React Testing Library to simulate user actions. ```jsx import { userEvent } from "@vitest/browser/context"; @@ -47,11 +53,11 @@ Unit tests focus on testing individual components or functions in isolation. }); ``` -## **Writing Browser Tests** +## Writing Browser Tests Browser testing involves testing the application in a web browser environment. Tools like [Puppeteer](https://pptr.dev/) can be used alongside Vitest. Please note Puppeteer does not come included by default in the RADFish framework. -1. **Basic Browser Test**: +1. **Basic Browser Test** ```jsx const puppeteer = require("puppeteer"); @@ -67,47 +73,44 @@ Browser testing involves testing the application in a web browser environment. T ## Additional Vitest Configuration -Vitest and React Testing Library is included in the RADFish framework by default. Modifying the Vitest test configuration can be configured in the `vite.config.js` file. Please see the official Vitest docs for the latest configuration options: [https://vitest.dev/config/](https://vitest.dev/config/). +Vitest and React Testing Library are included in the RADFish framework by default. The Vitest test configuration can be modified in the `vite.config.js` file. Refer to the official Vitest docs for the latest configuration options: [https://vitest.dev/config/](https://vitest.dev/config/). -## **Debugging Broken or Failed Tests** +## Debugging Broken or Failed Tests -1. **Review Test Output**: Vitest provides detailed error messages. Analyze them to understand the failure. -2. **Use `console.log`**: Temporarily add **`console.log`** statements within your test to inspect values. -3. **Check for Async Issues**: Ensure promises are resolved and state updates are completed. +1. **Review Test Output.** Vitest provides detailed error messages. Analyze them to understand the failure. +2. **Use `console.log`.** Temporarily add **`console.log`** statements within your test to inspect values. +3. **Check for Async Issues.** Ensure promises are resolved and state updates are completed. -## **Best Practices** +## Best Practices -1. **Descriptive Test Names**: Clearly describe what each test is checking. -2. **Small and Focused Tests**: Write tests that cover single functionalities. -3. **Avoid Over-Mocking**: Use mocks sparingly to ensure tests remain close to real-world scenarios. -4. **Test User Interactions**: Simulate how users interact with your application. -5. **Continuous Integration**: Integrate testing into your CI/CD pipeline for regular feedback. +By following these best practices, you can ensure your code works as expected. Testing also ensures your code will be maintainable over time. -Effective testing in React using Vitest and related frameworks is key to building robust applications. By following this section and adhering to best practices, you can ensure your React components work as expected and are maintainable over time. Remember, the goal of testing is not just to find bugs, but to build confidence in your codebase. +- **Descriptive Test Names.** Clearly describe what each test is checking. +- **Small and Focused Tests.** Write tests that cover single functionalities. +- **Avoid Over-Mocking.** Use mocks sparingly to ensure tests remain close to real-world scenarios. +- **Test User Interactions.** Simulate how users interact with your application. +- **Continuous Integration**. Integrate testing into your CI/CD pipeline for regular feedback. ## 508 Compliance +There are special steps to test whether your application meets 508 Compliance guidelines. Section 508 of the Rehabilitation Act mandates that federal agencies' electronic and information technology is accessible to people with disabilities, aligning with the Web Content Accessibility Guidelines (WCAG). -### 1. Introduction to Section 508 Compliance - - Section 508 of the Rehabilitation Act mandates that federal agencies' electronic and information technology is accessible to people with disabilities, aligning with the Web Content Accessibility Guidelines (WCAG). - -### 2. Set Up Your React Project +### 1. Set Up Your React Project - Ensure your React application is operational locally, typically accessed at `http://localhost:3000`. + Make sure your React application is operational locally, typically accessed at `http://localhost:3000`. -### 3. Automated Testing with Lighthouse +### 2. Automated Testing with Lighthouse - 1. **Open Google Chrome**: Ensure Google Chrome is installed and open your project by navigating to `http://localhost:3000`. - 2. **Access Chrome DevTools**: Right-click on the page and select "Inspect", or use `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Option+I` (Mac) to open DevTools. - 3. **Run Lighthouse Audit**: - - Click on the "Lighthouse" tab in the DevTools panel. - - Check the "Accessibility" box to focus the audit on accessibility compliance. - - Click "Analyze page load" to start the audit. Review the report that Lighthouse provides, detailing accessibility issues and suggestions for improvements. + 1. **Open Google Chrome.** Ensure Google Chrome is installed and open your project by navigating to `http://localhost:3000`. + 2. **Access Chrome DevTools.** Right-click on the page and select "Inspect", or use `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Option+I` (Mac) to open DevTools. + 3. **Run Lighthouse Audit.** + - Click on the "Lighthouse" tab in the DevTools panel. + - Check the "Accessibility" box to focus the audit on accessibility compliance. + - Click "Analyze page load" to start the audit. Review the report that Lighthouse provides, detailing accessibility issues and suggestions for improvements. -### 4. Implement Recommendations +### 3. Implement Recommendations - Address each listed accessibility issue based on Lighthouse’s suggestions, such as adding alt text to images, ensuring proper use of semantic HTML, and correcting ARIA labels. + Address each listed accessibility issue based on Lighthouse’s suggestions. For example, you might add alt text to images, use proper semantic HTML, or correct ARIA labels. -### 5. Rerun the Audit +### 4. Rerun the Audit - After making changes, rerun Lighthouse to verify improvements and ensure no new issues have arisen. + After making changes, run Lighthouse again. This will verify improvements and ensure no new issues have arisen. From 208c2ddee90f5b3f1d24b98af3ac18b6f961a618 Mon Sep 17 00:00:00 2001 From: oanelson Date: Wed, 4 Dec 2024 17:28:43 -0800 Subject: [PATCH 6/9] Closes 165 --- .../building-your-application/available-scripts/index.mdx | 6 +++--- .../available-scripts/installing-cli.md | 2 +- .../available-scripts/running-example.md | 6 +++--- .../building-your-application/service-worker-removal.md | 3 +-- 4 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/developer-documentation/building-your-application/available-scripts/index.mdx b/docs/developer-documentation/building-your-application/available-scripts/index.mdx index 3a3100d..a646d32 100644 --- a/docs/developer-documentation/building-your-application/available-scripts/index.mdx +++ b/docs/developer-documentation/building-your-application/available-scripts/index.mdx @@ -21,11 +21,11 @@ Starts the Vite development server. It runs the app locally with hot module relo **`npm run build`** -This script builds the project for production by using Vite’s build tool. It generates optimized static assets, such as HTML, CSS, and JavaScript, which are output to the dist directory. +This script builds the project for production by using Vite’s build tool. It generates optimized static assets, such as HTML, CSS, and JavaScript, which are output to the `dist` directory. **`npm run prebuild`** -Before the build process starts, this script ensures that the dist folder (which contains the previous build) is deleted. This helps prevent old build files from being included in the new build. +Before the build process starts, this script deletes the `dist` folder (which contains the previous build). This helps prevent old build files from being included in the new build. **`npm test`** @@ -37,7 +37,7 @@ Runs end-to-end (e2e) tests located in `./src/__tests__/e2e/integration.e2e.test **`npm run lint`** -Runs ESLint with the `--fix` option, which automatically fixes certain linting issues in the code found in the src/ directory. +Runs ESLint with the `--fix` option, which automatically fixes certain linting issues in the code found in the `src/` directory. **`npm run format`** diff --git a/docs/developer-documentation/building-your-application/available-scripts/installing-cli.md b/docs/developer-documentation/building-your-application/available-scripts/installing-cli.md index 848ac06..9df7cb0 100644 --- a/docs/developer-documentation/building-your-application/available-scripts/installing-cli.md +++ b/docs/developer-documentation/building-your-application/available-scripts/installing-cli.md @@ -8,7 +8,7 @@ The RADFish CLI is available as an `npm` package, making the installation proces ## Install the CLI -To install the RADFish CLI globally on your system, run the following command: +To install the RADFish CLI globally on your system, run this command: ```bash npm install -g @nmfs-radfish/create-radfish-app diff --git a/docs/developer-documentation/building-your-application/available-scripts/running-example.md b/docs/developer-documentation/building-your-application/available-scripts/running-example.md index ba9f149..1b92ebc 100644 --- a/docs/developer-documentation/building-your-application/available-scripts/running-example.md +++ b/docs/developer-documentation/building-your-application/available-scripts/running-example.md @@ -4,12 +4,12 @@ sidebar_position: 2 # Running an Example -RADFish ships with several different [boilerplate examples](../../examples-and-templates#examples) that demonstrate core pieces of functionality. These examples have been identified as critical for NOAA application development and demonstrate best practices. You can use these examples as a reference point to build out your own implementation. They can also serve as inspiration for your own designs. +RADFish ships with several different [boilerplate examples](../../examples-and-templates#examples). These examples demonstrate core functions identified as critical for NOAA application development. You can use these examples as a reference point to build out your own implementation. Or, they may serve as inspiration for your own designs and best practices. -For instance, there is an example that demonstrates how to build a multi-step form that caches each step within IndexedDB. Cacheing allows data to be referenced without having a network connection. To run this example, use the following command: +For instance, there's an example that demonstrates how to build a multi-step form that caches each step within IndexedDB. Caching the form allows it to be referenced without a network connection. In order to run this example, you can run this command: `npx @nmfs-radfish/create-radfish-app my-app --example multistep-form` -This will clone the code from the `multistep-form` onto your machine, and spawn a new web process on port `3000` or another port if that is already taken. +This will clone the code from the `multistep-form` onto your machine. It also spawns a new web process on port `3000` or another port if that is already taken. Feel free to use this code and modify it for your needs! diff --git a/docs/developer-documentation/building-your-application/service-worker-removal.md b/docs/developer-documentation/building-your-application/service-worker-removal.md index 36866dd..c6ef252 100644 --- a/docs/developer-documentation/building-your-application/service-worker-removal.md +++ b/docs/developer-documentation/building-your-application/service-worker-removal.md @@ -5,7 +5,7 @@ title: Service Worker Removal ### Removing the Preconfigured Service Worker -> **Disclaimer:** The service worker in this template is designed to provide offline functionality and improve app performance. Removing it is generally not recommended. However, if needed, follow these steps: +**Disclaimer:** The service worker in this template is designed to provide offline functionality and improve app performance. Removing it is generally not recommended. However, if needed, follow these steps: 1. **Uninstall the Service Worker Plugin** Run the following command to uninstall `vite-plugin-pwa`: @@ -19,4 +19,3 @@ title: Service Worker Removal In your `src/index.js` file, remove the service worker configurations. After these steps, the service worker will be removed from the application. - From 4ab8d66aa2f3da14bb3f0957a3a4c9a067b5bdaa Mon Sep 17 00:00:00 2001 From: Jay Giang Date: Thu, 5 Dec 2024 13:55:49 -0800 Subject: [PATCH 7/9] Add back script header --- docs/developer-documentation/getting-started.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/developer-documentation/getting-started.md b/docs/developer-documentation/getting-started.md index cb1aae5..61c101f 100644 --- a/docs/developer-documentation/getting-started.md +++ b/docs/developer-documentation/getting-started.md @@ -77,6 +77,7 @@ npx @nmfs-radfish/create-radfish-app --help ``` Please visit [upgrading](./upgrading.md) for more information. +## Scripts See [Available Scripts](./building-your-application/available-scripts) for full list of commands. The **`npm start`** script starts the Vite development server. It runs the app locally with hot module reloading, allowing for fast development and instant updates as you make changes. Open [http://localhost:3000](http://localhost:3000/) to view it in the browser. From a0dc2ddf5264436118560b6a37287c287bb89313 Mon Sep 17 00:00:00 2001 From: Jay Giang Date: Thu, 5 Dec 2024 14:09:17 -0800 Subject: [PATCH 8/9] Change scripts order --- docs/developer-documentation/getting-started.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/developer-documentation/getting-started.md b/docs/developer-documentation/getting-started.md index 61c101f..3db66ea 100644 --- a/docs/developer-documentation/getting-started.md +++ b/docs/developer-documentation/getting-started.md @@ -77,10 +77,11 @@ npx @nmfs-radfish/create-radfish-app --help ``` Please visit [upgrading](./upgrading.md) for more information. -## Scripts -See [Available Scripts](./building-your-application/available-scripts) for full list of commands. +**`npm start`** + +This script starts the Vite development server. It runs the app locally with hot module reloading, allowing for fast development and instant updates as you make changes. Open [http://localhost:3000](http://localhost:3000/) to view it in the browser. -The **`npm start`** script starts the Vite development server. It runs the app locally with hot module reloading, allowing for fast development and instant updates as you make changes. Open [http://localhost:3000](http://localhost:3000/) to view it in the browser. +See [Available Scripts](./building-your-application/available-scripts) for full list of commands. ## Next steps Now that you are up and running, see the [Components & Usage](./building-your-application/patterns/components.md) section to start building out your first pages! From d90f79c1f105eda77eed34917220353886c2c9b9 Mon Sep 17 00:00:00 2001 From: Jay Giang Date: Thu, 5 Dec 2024 14:10:25 -0800 Subject: [PATCH 9/9] Add back Scripts header --- docs/developer-documentation/getting-started.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/developer-documentation/getting-started.md b/docs/developer-documentation/getting-started.md index 3db66ea..deb980f 100644 --- a/docs/developer-documentation/getting-started.md +++ b/docs/developer-documentation/getting-started.md @@ -77,6 +77,8 @@ npx @nmfs-radfish/create-radfish-app --help ``` Please visit [upgrading](./upgrading.md) for more information. +# Scripts + **`npm start`** This script starts the Vite development server. It runs the app locally with hot module reloading, allowing for fast development and instant updates as you make changes. Open [http://localhost:3000](http://localhost:3000/) to view it in the browser.