{"type":"doc","content":[{"type":"paragraph","content":[{"text":"This is a compendium of the coding conventions we use in O3. The purpose of this document is to help us write code that is consistent and easy to maintain.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Naming","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Follow the guidelines in this ","type":"text"},{"text":"naming cheatsheet(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/kettanaito/naming-cheatsheet"}}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"camelCase","type":"text","marks":[{"type":"code"}]},{"text":" for variables, functions, methods, and class names.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"kebab-case","type":"text","marks":[{"type":"code"}]},{"text":" for file names and folder names.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Components should contain the ","type":"text"},{"text":".component","type":"text","marks":[{"type":"code"}]},{"text":" suffix in their name (e.g. ","type":"text"},{"text":"user.component.tsx","type":"text","marks":[{"type":"code"}]},{"text":"). This nomenclature is used to distinguish components from other files such as resources, stylesheets, and tests, and determines where translation keys and strings should be extracted from. Translation keys and strings will not be extracted from files that do not match this convention.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Components may also contain different types of suffixes to indicate their purpose. These custom suffixes should be used in addition to the ","type":"text"},{"text":".component","type":"text","marks":[{"type":"code"}]},{"text":" suffix. They include:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".extension","type":"text","marks":[{"type":"code"}]},{"text":" for components that render extensions e.g. ","type":"text"},{"text":"lab-order-basket-panel.extension.tsx(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-esm-patient-chart/blob/main/packages/esm-patient-labs-app/src/lab-orders/lab-order-basket-panel/lab-order-basket-panel.extension.tsx#L21"}}]},{"text":" for the Lab Order Basket panel extension.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".modal","type":"text","marks":[{"type":"code"}]},{"text":" for components that render modals e.g. ","type":"text"},{"text":"delete-condition.modal.tsx(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-esm-patient-chart/blob/main/packages/esm-patient-conditions-app/src/conditions/delete-condition.modal.tsx"}}]},{"text":" for the Delete Conditions modal.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".workspace","type":"text","marks":[{"type":"code"}]},{"text":" for components that render forms in the workspace e.g. ","type":"text"},{"text":"order-basket.workspace.tsx(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-esm-patient-chart/blob/main/packages/esm-patient-orders-app/src/order-basket/order-basket.workspace.tsx#L4"}}]},{"text":" for the Order Basket workspace.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Unit and integration test files should contain the ","type":"text"},{"text":".test","type":"text","marks":[{"type":"code"}]},{"text":" suffix in their name (e.g. ","type":"text"},{"text":"user.test.tsx","type":"text","marks":[{"type":"code"}]},{"text":"). Do not include the word ","type":"text"},{"text":"component","type":"text","marks":[{"type":"code"}]},{"text":" in the test file name.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Playwright e2e tests should contain the '.spec' suffix in their name (e.g. ","type":"text"},{"text":"user.spec.ts","type":"text","marks":[{"type":"code"}]},{"text":").","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Stylesheets should not contain ","type":"text"},{"text":".component","type":"text","marks":[{"type":"code"}]},{"text":" suffix in their name (e.g. ","type":"text"},{"text":"user.component.scss","type":"text","marks":[{"type":"code"}]},{"text":"). This is because stylesheets are not components, and are not translated by the translation system. Instead, stylesheets should be named after the component they are styling (e.g. ","type":"text"},{"text":"user.scss","type":"text","marks":[{"type":"code"}]},{"text":").","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Resource files that encapsulate data fetching logic should contain the ","type":"text"},{"text":".resource","type":"text","marks":[{"type":"code"}]},{"text":" suffix in their name (e.g. ","type":"text"},{"text":"user.resource.ts","type":"text","marks":[{"type":"code"}]},{"text":"). This is to distinguish them from other files such as components, stylesheets, and tests.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Name TypeScript files that contain JSX with the ","type":"text"},{"text":".tsx","type":"text","marks":[{"type":"code"}]},{"text":" extension (e.g. ","type":"text"},{"text":"user.component.tsx","type":"text","marks":[{"type":"code"}]},{"text":"). Name TypeScript files that do not contain JSX with the ","type":"text"},{"text":".ts","type":"text","marks":[{"type":"code"}]},{"text":" extension (e.g. ","type":"text"},{"text":"user.resource.ts","type":"text","marks":[{"type":"code"}]},{"text":"). In most cases, you shouldn't need to use the ","type":"text"},{"text":".tsx","type":"text","marks":[{"type":"code"}]},{"text":" extension for files outside the ","type":"text"},{"text":"src","type":"text","marks":[{"type":"code"}]},{"text":" directory.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Follow the extension system ","type":"text"},{"text":"nomenclature guide","type":"text","marks":[{"type":"link","attrs":{"href":"https://o3-docs.openmrs.org/docs/extension-system#nomenclature"}}]},{"text":" when naming your extensions and extension slots.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use the file name as the component name. For example, ","type":"text"},{"text":"user.component.tsx","type":"text","marks":[{"type":"code"}]},{"text":" should contain a component named ","type":"text"},{"text":"UserComponent","type":"text","marks":[{"type":"code"}]},{"text":". This makes it easier to find the component in the codebase.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid using DOM component prop names for different purposes. For example, avoid using the ","type":"text"},{"text":"className","type":"text","marks":[{"type":"code"}]},{"text":" prop to pass a CSS class name to a component. Instead, use a prop name that is specific to the component, such as ","type":"text"},{"text":"cssClass","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"camelCase","type":"text","marks":[{"type":"code"}]},{"text":" for prop names. This is consistent with the naming convention for variables, functions, and methods.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Translation keys should be in ","type":"text"},{"text":"camelCase","type":"text","marks":[{"type":"code"}]},{"text":" whereas translation strings should be in ","type":"text"},{"text":"sentence case","type":"text","marks":[{"type":"code"}]},{"text":". For example, ","type":"text"},{"text":"firstName","type":"text","marks":[{"type":"code"}]},{"text":" is a translation key whereas ","type":"text"},{"text":"First name","type":"text","marks":[{"type":"code"}]},{"text":" is it's corresponding translation string.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Frontend modules in monorepos should have names that start with the ","type":"text"},{"text":"esm-","type":"text","marks":[{"type":"code"}]},{"text":" prefix. The name of the module should describe what the module does. For example, ","type":"text"},{"text":"esm-user-management","type":"text","marks":[{"type":"code"}]},{"text":" is a good name for a frontend module handling user management concerns.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Event handler props should be named after they event they handle ","type":"text"},{"text":"e.g. onClick","type":"text","marks":[{"type":"code"}]},{"text":" for a click handler. By convention, event handler props should start with the ","type":"text"},{"text":"on","type":"text","marks":[{"type":"code"}]},{"text":" prefix, followed by a capital letter.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"State updater functions should be named after the state they update. For example, ","type":"text"},{"text":"setFirstName","type":"text","marks":[{"type":"code"}]},{"text":" is a good name for a state updater function that updates the ","type":"text"},{"text":"firstName","type":"text","marks":[{"type":"code"}]},{"text":" state.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"What to name your branches is typically down to personal preference. However, when in doubt, name your branches using the ","type":"text"},{"text":"conventional commit(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.conventionalcommits.org/en/v1.0.0/"}}]},{"text":" type that your work conforms to, followed by a slash and a short dash-separated description of the work. Good examples include: ","type":"text"},{"text":"feat/debounced-order-basket-search","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"fix/missing-translation","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"chore/bump-dependencies","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"refactor/remove-unused-code","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Project structure","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Monorepos should contain domain-specific packages that are related to each other. For example, patient management concerns such as registration and search live in the ","type":"text"},{"text":"openmrs-esm-patient-management","type":"text","marks":[{"type":"code"}]},{"text":" monorepo.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Configuration files should generally exist at the top level of the monorepo directory. Notable exceptions to this rule include the a file containing helpers for tests, the ","type":"text"},{"text":"i18next-parser","type":"text","marks":[{"type":"code"}]},{"text":" configuration, and ","type":"text"},{"text":"setupTests.ts","type":"text","marks":[{"type":"code"}]},{"text":", which should all exist in the ","type":"text"},{"text":"tools","type":"text","marks":[{"type":"code"}]},{"text":" directory.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Colocate files that are related to each other. For example, a component and its corresponding test and stylesheet should live in the same directory. This way, when you make a change to a component, it's easy to extend that change to the test and stylesheet if necessary.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid placing styles for multiple components in the same stylesheet. Instead, create a separate stylesheet for each component. This makes it easier to find the styles for a particular component.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Components","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Don't keep unused code in your components. Keeping dead code around can cause confusion and makes it harder to maintain the codebase.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Validate the props passed to your component using type aliases or interfaces. This helps to catch bugs early and makes it easier to understand how the component is used.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Make sure you read through the Component API for a particular Carbon component before using it. This helps you to understand the component's props and how to use them. It also helps you to understand the component's behavior and can obviate the need for writing custom code. For example, here's the ","type":"text"},{"text":"Component API for the Button component(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://react.carbondesignsystem.com/?path=/docs/components-button--default"}}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use keys in lists(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://react.dev/learn/rendering-lists"}}]},{"text":". This helps React to identify which items have changed, been added, or been removed. This is especially important if you are rendering a list of components that contain state.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Generate keys from the data itself(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://react.dev/learn/rendering-lists#where-to-get-your-key"}}]},{"text":" if possible. For example, if you are rendering a list of patients from the database, use the patient's ID as the key. This ensures that the key is unique and stable across renders.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid using effects(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://react.dev/learn/you-might-not-need-an-effect"}}]},{"text":" for things that don't involve synchronizing with external systems. The distinction is nuanced and can be difficult to understand. Please read and internalize the linked article before reaching for effects.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Don't reach for performance optimizations like memo, useMemo and useCallback before you need them. These optimizations come at a cost, and can make your code harder to understand. Read ","type":"text"},{"text":"this article(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://kentcdodds.com/blog/usememo-and-usecallback"}}]},{"text":" and ","type":"text"},{"text":"this article(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://overreacted.io/before-you-memo/#solution-2-lift-content-up"}}]},{"text":" to understand when to use these hooks.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Omit the value of a prop when it is explicitly ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":". For example, ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" is preferred over ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Follow consistent code formatting, naming conventions and folder structure. This makes the codebase more readable and easier to maintain.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Data fetching","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Colocate your data fetching logic in a file suffixed with ","type":"text"},{"text":".resource","type":"text","marks":[{"type":"code"}]},{"text":". For example, ","type":"text"},{"text":"user.resource.ts","type":"text","marks":[{"type":"code"}]},{"text":" contains the data fetching logic for the user resource.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Wherever possible, prefer abstracting your data fetching into a custom hook rather than ","type":"text"},{"text":"fetching with effects(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://react.dev/reference/react/useEffect#fetching-data-with-effects"}}]},{"text":". Fetching data with effects has many ","type":"text"},{"text":"downsides(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://react.dev/reference/react/useEffect#fetching-data-with-effects"}}]},{"text":" and should be avoided. Instead, prefer using ","type":"text"},{"text":"SWR(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://swr.vercel.app/"}}]},{"text":" hooks.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"SWR(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://swr.vercel.app/"}}]},{"text":" hooks to fetch data from the backend. Use SWRImmutable for resources that are not expected to change often, such as backend configurations.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Put the SWR hook in a separate file, and export it as a function. This allows us to reuse the same hook in multiple components.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Memoize the return value of your SWR hook using ","type":"text"},{"text":"useMemo","type":"text","marks":[{"type":"code"}]},{"text":" to prevent unnecessary rerenders. This is especially important if the hook is used in a component that is rendered many times, such as a table row.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Data fetching hooks should follow the naming convention ","type":"text"},{"text":"use","type":"text","marks":[{"type":"code"}]},{"text":". For example, ","type":"text"},{"text":"useUser","type":"text","marks":[{"type":"code"}]},{"text":" is the hook for fetching user data.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"openmrsFetch","type":"text","marks":[{"type":"code"}]},{"text":" to fetch data from the backend. openmrsFetch is a wrapper around the ","type":"text"},{"text":"fetch","type":"text","marks":[{"type":"code"}]},{"text":" API that adds authentication and authorization headers and handles errors. Pass it to ","type":"text"},{"text":"useSWR","type":"text","marks":[{"type":"code"}]},{"text":" as the ","type":"text"},{"text":"fetcher","type":"text","marks":[{"type":"code"}]},{"text":" argument of your SWR hooks.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"openmrsObservableFetch","type":"text","marks":[{"type":"code"}]},{"text":" only if you need to fetch data from the backend using an observable. This is useful for streaming data from the backend. Ensure you understand the difference between observables and promises before reaching for this function.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Internationalization","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not manually edit any of the locale-speficic translation files in the ","type":"text"},{"text":"translations","type":"text","marks":[{"type":"code"}]},{"text":" directory. Run the ","type":"text"},{"text":"extract-translations","type":"text","marks":[{"type":"code"}]},{"text":" script instead to keep the ","type":"text"},{"text":"en.json","type":"text","marks":[{"type":"code"}]},{"text":" file in sync with the translation keys in the codebase.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use the ","type":"text"},{"text":"useTranslation(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://react.i18next.com/latest/usetranslation-hook"}}]},{"text":" hook to translate strings in your components.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use the ","type":"text"},{"text":"Trans(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://react.i18next.com/latest/trans-component"}}]},{"text":" component to translate strings that contain HTML tags.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"To handle pluralization, use the following pattern:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"tsx"},"content":[{"text":"// If there's only one risk flag, the string \"1 risk flag\" is displayed.// If there are multiple risk flags, the string \"{count} risk flags\" is displayed// e.g. \"3 risk flags\". {t(\"flagCount\", { count: riskFlags.length, })}","type":"text"}]},{"type":"paragraph","content":[{"text":"The corresponding keys and strings for the code above should look like this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"\"flagCount_one\": \"{{ count }} risk flag\",\"flagCount_other\": \"{{ count }} risk flags\"","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"State management","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Follow the guidelines outlined ","type":"text"},{"text":"here(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://kentcdodds.com/blog/application-state-management-with-react"}}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"To share state between components, ","type":"text"},{"text":"lift the state up to the nearest common ancestor(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://react.dev/learn/sharing-state-between-components#"}}]},{"text":" of the components that need to share the state and pass the state down to the components as props. This is the simplest way to share state between components.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid creating state variables for things that can be ","type":"text"},{"text":"computed from existing state variables(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://react.dev/learn/you-might-not-need-an-effect#updating-state-based-on-props-or-state"}}]},{"text":". For example, if you have a state variable called ","type":"text"},{"text":"firstName","type":"text","marks":[{"type":"code"}]},{"text":" and another called ","type":"text"},{"text":"lastName","type":"text","marks":[{"type":"code"}]},{"text":", don't create a third state variable called ","type":"text"},{"text":"fullName","type":"text","marks":[{"type":"code"}]},{"text":". Instead, derive the ","type":"text"},{"text":"fullName","type":"text","marks":[{"type":"code"}]},{"text":" from the ","type":"text"},{"text":"firstName","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"lastName","type":"text","marks":[{"type":"code"}]},{"text":" state variables.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Mutations and side effects","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use SWR's global and bound ","type":"text"},{"text":"mutate(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://swr.vercel.app/docs/mutation#mutate"}}]},{"text":" APIs to mutate data in the cache. This ensures that the cache is updated consistently across the application and omits the need to reload the page to see the changes.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Show a toast notification when a mutation succeeds. When a mutation fails, show a inline notification with an error message that communicates the reason for the failure.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Event handlers","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Ensure that your event handlers properly define their cleanup logic. Event handlers in useEffect callbacks should always ","type":"text"},{"text":"return","type":"text","marks":[{"type":"em"}]},{"text":" a cleanup function to prevent unexpected behaviour. For example, do this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"tsx"},"content":[{"text":"useEffect(() => { const handleClick = () => { // ... handle the click event }; document.addEventListener(\"click\", handleClick); return () => { document.removeEventListener(\"click\", handleClick); };}, []);","type":"text"}]},{"type":"paragraph","content":[{"text":"Instead of this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"tsx"},"content":[{"text":"useEffect(() => { const handleClick = () => { // ... handle the click event }; document.addEventListener(\"click\", handleClick); // Incorrect cleanup: Executes immediately, not when the component unmounts document.removeEventListener(\"click\", handleClick);}, []);","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Type annotations","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Follow the guidelines outlined in ","type":"text"},{"text":"React TypeScript Cheatsheets(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/basic_type_example/"}}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Always annotate your function parameters with types. This makes it easier to understand what the function does, and explicitly expresses the function's contracts.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Rely on TypeScript's type inference for things like variable and array initialization, and in some cases, function return types. The goal of the type system is not to annotate every single variable with a type, but rather to make sure that the important parts of your code are type-safe. Read more about type inference ","type":"text"},{"text":"here(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.typescriptlang.org/docs/handbook/type-inference.html"}}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"TypeScript ","type":"text"},{"text":"interfaces","type":"text","marks":[{"type":"code"}]},{"text":" enable declaration merging and can be extended by other interfaces. This makes them more flexible than ","type":"text"},{"text":"type","type":"text","marks":[{"type":"code"}]},{"text":" aliases, which cannot be extended. If you don't need these features, prefer using ","type":"text"},{"text":"type","type":"text","marks":[{"type":"code"}]},{"text":" aliases instead.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Don't use ","type":"text"},{"text":"any","type":"text","marks":[{"type":"code"}]},{"text":" unless you absolutely have to. Instead, use ","type":"text"},{"text":"unknown","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"never","type":"text","marks":[{"type":"code"}]},{"text":" to express the fact that you don't know the type of a variable or that a function never returns.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Wherever possible, use the ","type":"text"},{"text":"import type","type":"text","marks":[{"type":"code"}]},{"text":" syntax when importing types. This prevents the type from being imported at runtime, which reduces the bundle size. For example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"ts"},"content":[{"text":"// Preferimport type { User } from \"@openmrs/esm-user-management\"; // Instead ofimport { User } from \"@openmrs/esm-user-management\";","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Prefer union types over status enums(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://fettblog.eu/tidy-typescript-avoid-enums/"}}]},{"text":". For example, prefer ","type":"text"},{"text":"type Status = \"loading\" | \"error\" | \"success\"","type":"text","marks":[{"type":"code"}]},{"text":" over ","type":"text"},{"text":"enum Status { Loading, Error, Success }","type":"text","marks":[{"type":"code"}]},{"text":". This is because enums are not type safe, and can be assigned any value. For example, ","type":"text"},{"text":"Status.Loading = \"error\"","type":"text","marks":[{"type":"code"}]},{"text":" is a valid statement, but ","type":"text"},{"text":"Status = \"error\"","type":"text","marks":[{"type":"code"}]},{"text":" is not.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use the ","type":"text"},{"text":"jest.mocked","type":"text","marks":[{"type":"code"}]},{"text":" utility to preserve type information when mocking functions in tests. For example:","type":"text"}]},{"type":"paragraph","content":[{"text":"Prefer:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"ts"},"content":[{"text":"const mockedShowSnackbar = jest.mocked(showSnackbar); // All the type information is preserved","type":"text"}]},{"type":"paragraph","content":[{"text":"Over:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"ts"},"content":[{"text":"const mockedShowSnackbar = showSnackbar as jest.Mock;","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Styling","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Be wary of using global styles. They can easily lead to unintended side effects and make it difficult to reason about the codebase. Nest global styles under a class name to prevent them from affecting other components.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"scss"},"content":[{"text":"// Avoid applying styles globally:global(.cds--text-input) { height: 3rem; @extend .label01;} // Prefer scoping style overrides under a class name.input-group { display: flex; justify-content: center; flex-direction: column; :global(.cds--text-input) { height: 3rem; @extend .label01; }}","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Put Carbon style overrides in ","type":"text"},{"text":"overrides.scss(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-styleguide/src/_overrides.scss"}}]},{"text":". This ensures that the overrides are applied consistently across the application.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Prefer using Carbon ","type":"text"},{"text":"color(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://carbondesignsystem.com/guidelines/color/overview/"}}]},{"text":", ","type":"text"},{"text":"spacing(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://carbondesignsystem.com/guidelines/spacing/overview/"}}]},{"text":" and ","type":"text"},{"text":"type(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://carbondesignsystem.com/guidelines/typography/overview/"}}]},{"text":" tokens over hard-coded values. Below are some examples of using tokens in code:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"scss"},"content":[{"text":"@use \"@carbon/styles/scss/colors\";@use \"@carbon/styles/scss/spacing\";@use \"@carbon/styles/scss/type\"; .listWrapper { margin: spacing.$spacing-05;} .resultsCount { @include type.type-style(\"label-01\");} .sortDropdown { color: colors.$gray-100; gap: 0;}","type":"text"}]},{"type":"paragraph","content":[{"text":"Find a useful reference for color token mappings ","type":"text"},{"text":"here(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://carbon-elements.netlify.app/colors/examples/preview/"}}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use SASS ","type":"text"},{"text":"features(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://sass-lang.com/documentation"}}]},{"text":" like interpolation, at-rules, mixins, and functions to make your styles more reusable and maintainable.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If you want to apply styles based on the user's viewport size, use our predefined ","type":"text"},{"text":"breakpoints(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-styleguide/src/breakpoints/index.ts"}}]},{"text":". For example, to apply different styles for tablet and desktop viewports, do this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"scss"},"content":[{"text":"// Tablet viewports:global(.omrs-breakpoint-lt-desktop) { .form { height: calc(100vh - 9rem); }} // Desktop viewports:global(.omrs-breakpoint-gt-tablet) { .form { height: calc(100vh - 6rem); }}","type":"text"}]},{"type":"paragraph","content":[{"text":"ℹ️","type":"text"}]},{"type":"paragraph","content":[{"text":"Make sure to scope your styles under a class name (such as ","type":"text"},{"text":".form","type":"text","marks":[{"type":"code"}]},{"text":" in the example above) to avoid them affecting other components.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use the ","type":"text"},{"text":"classnames(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://npm.im/classnames"}}]},{"text":" library to conditionally apply styles to an element. Consider using classnames if you're interpolating multiple class names into a string. For example, the following snippet:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"tsx"},"content":[{"text":"","type":"text"}]},{"type":"paragraph","content":[{"text":"Could be replaced by:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"tsx"},"content":[{"text":"import classnames from \"classnames\"; ;","type":"text"}]},{"type":"paragraph","content":[{"text":"The following snippet shows a more advanced case - a ","type":"text"},{"text":"div","type":"text","marks":[{"type":"code"}]},{"text":" styled with multiple conditional styles:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"tsx"},"content":[{"text":"return (

// ... details omitted for brevity

);","type":"text"}]},{"type":"paragraph","content":[{"text":"You can refactor this snippet to leverage ","type":"text"},{"text":"classnames","type":"text","marks":[{"type":"code"}]},{"text":" as follows:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"tsx"},"content":[{"text":"import classNames from \"classnames\"; const containerClasses = classNames(styles.textInputContainer, { [styles.disabledInput]: disabled, [styles.danger]: !isWithinNormalRange, [muacColorCode]: useMuacColors,}); return

// ... details omitted for brevity

;","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Search inputs","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Debounce search inputs to prevent unnecessary requests to the backend. Use the ","type":"text"},{"text":"useDebounce(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-esm-core/blob/2396ab96a37bc7202c853110969d82c17fe098a6/packages/framework/esm-react-utils/src/useDebounce.ts"}}]},{"text":" hook to debounce search inputs. Here's a snippet (some bits are omitted for brevity) showing how you could use the hook:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"tsx"},"content":[{"text":"const [searchTerm, setSearchTerm] = useState(\"\");const debouncedSearchTerm = useDebounce(searchTerm); return ( ) => setSearchTerm(e.target.value)} placeholder={t(\"searchThisList\", \"Search this list\")} />); // Do something with the debouncedSearchTerm","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"fuzzy(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://npm.im/fuzzy"}}]},{"text":" to implement fuzzy search. Fuzzy search is a strategy for matching search terms that are similar to, but not exactly the same as, the search term. For example, if the search term is ","type":"text"},{"text":"John","type":"text","marks":[{"type":"code"}]},{"text":", fuzzy search will match ","type":"text"},{"text":"Jon","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"Jhon","type":"text","marks":[{"type":"code"}]},{"text":", and ","type":"text"},{"text":"Johhn","type":"text","marks":[{"type":"code"}]},{"text":". This is useful for matching search terms that are misspelled or contain typos. Here's how we can leverage fuzzy to enhance the search experience from the snippet above:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"tsx"},"content":[{"text":"const [filter, setFilter] = useState(\"\"); const filteredForms: Array = useMemo(() => { if (!debouncedSearchTerm) { if (filter === \"Retired\") { return forms.filter((form) => form.retired); } if (filter === \"Published\") { return forms.filter((form) => form.published); } if (filter === \"Unpublished\") { return forms.filter((form) => !form.published); } return forms; } return debouncedSearchTerm ? fuzzy .filter(debouncedSearchTerm, forms, { extract: (form: TypedForm) => `${form.name} ${form.version}`, }) .sort((r1, r2) => r1.score - r2.score) .map((result) => result.original) : forms;}, [filter, forms, debouncedSearchTerm]);","type":"text"}]},{"type":"paragraph","content":[{"text":"We're using the ","type":"text"},{"text":"debouncedSearchTerm","type":"text","marks":[{"type":"code"}]},{"text":" from the snippet above to filter the list of forms. We're also using the ","type":"text"},{"text":"extract","type":"text","marks":[{"type":"code"}]},{"text":" option to tell fuzzy how to extract the search term from the form. In this case, we're extracting the search term from the form's name and version. This is because we want to match forms that contain the search term in their name or version. Finally, we're sorting the results by score, which is a measure of how closely the search term matches the form.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Testing","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid the test user(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://kentcdodds.com/blog/avoid-the-test-user"}}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid testing implementation details. Instead, test the component's public API. This makes it easier to refactor the component without having to rewrite the tests.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Follow the guidelines outlined ","type":"text"},{"text":"here(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://kentcdodds.com/blog/common-mistakes-with-react-testing-library"}}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Don't make these common testing ","type":"text"},{"text":"mistakes(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://kentcdodds.com/blog/common-testing-mistakes"}}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Write fewer, longer tests(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://kentcdodds.com/blog/write-fewer-longer-tests"}}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Structure large test suites using ","type":"text"},{"text":"object page models(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://playwright.dev/docs/pom"}}]},{"text":" when writing e2e tests using Playwright.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Follow the e2e testing ","type":"text"},{"text":"best practices(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://playwright.dev/docs/test-best-practices"}}]},{"text":" outlined in the Playwright docs.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Functions from ","type":"text"},{"text":"@openmrs/esm-framework","type":"text","marks":[{"type":"code"}]},{"text":" get ","type":"text"},{"text":"mocked(opens in a new tab)","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-framework/mock.tsx"}}]},{"text":" automatically when running tests. To override the default mock, use the ","type":"text"},{"text":"jest.mock","type":"text","marks":[{"type":"code"}]},{"text":" API. For example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"ts"},"content":[{"text":"// Override the default mock for usePatientjest.mock(\"@openmrs/esm-framework\", () => ({ ...jest.requireActual(\"@openmrs/esm-framework\"), usePatient: jest.fn(() => ({ uuid: \"some-uuid\" })),}));","type":"text"}]},{"type":"paragraph","content":[{"text":"Remember to update the mock when you modify or add a new function to ","type":"text"},{"text":"@openmrs/esm-framework","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]}]}],"version":1}