lib-customizations

lib-customizations

Package to enable customizing eVaka frontend(s) in forks without requiring merges or upstreaming all possible configurations.

Usage

NOTE: No new library dependencies can be installed as all the customization files are included in the main eVaka lib-customizations builds as is, and don't form a separate package/project.

NOTE 2: Currently employee-mobile-frontend isn't included but can be added later on.

Assuming directory layout like:

myfork/
├── frontend/
│   └── mytown/ # <- Your customizations, matches espoo/ contents
│          ├── citizen.tsx
│          └── ...
└── evaka/ (git submodule or similar)
    └── frontend/
        └── src/
            └── lib-customizations/
                ├── espoo/      # <- Default customizations for Espoo
                ├── citizen.tsx # <- "root modules" that expose customizations
                └── ...

1. Link your own directory to ./<your customization>

   • E.g. with symbolic or hard links:

     # Running in evaka/frontend.
     # Assuming your customizations name is "mytown" and is placed in ../../frontend/mytown.
     ln -v -s $(readlink -f ../../frontend/mytown) src/lib-customizations/mytown

2. Run the build / dev server with EVAKA_CUSTOMIZATIONS=<your customization>, e.g.:

   # Build
   EVAKA_CUSTOMIZATIONS=mytown yarn build
   
   # Dev
   EVAKA_CUSTOMIZATIONS=mytown yarn dev

   • Applies to all Webpack actions

3. Customizations can freely be split into multiple files but everything must be reachable by following the import chain from the main files:

   • citizen.tsx
   • employee.tsx
   • common.tsx

Creating customizable modules

Customizations generally consist of five basic parts:

1. Type definitions in types.d.ts

2. Import & export in one of the "root" modules, e.g. citizen.tsx, using the @evaka/customizations/<module> style of import paths (replaced by Webpack dynamically at build time)

3. Actual implementation and export in <customization>/<module>, e.g. mytown/citizen.tsx

4. Default implementation in espoo/<module>, e.g. espoo/citizen.tsx

5. Import and usage of customized module in a project:

   // Note the import path: nothing about "espoo"
   import { featureFlags } from 'lib-customizations/citizen'
   
   if (featureFlags.urgencyAttachmentsEnabled) {
     doStuff()
   }

NOTE: You might need to update frontend/.gitignore to add some new files.

Special cases

Imports outside TypeScript modules

By default, everything should be exposed in the root modules and imported by standard ES imports (import ... from ...) but when importing something handled only by Webpack (i.e. file loader, most commonly), use the dynamically replaced path:

<link rel="shortcut icon" href="<%= require('@evaka/customizations/assets/favicon.ico') %>">