Getting Started on your first FOLIO UI module

This tutorial requires Git, NodeJS and Yarn.

It includes screenshots from the VS CODE UI to display directory/file structure.

1. Create a single development folder for your workspace. We’ll call it the “FOLIO_Workspace” folder for sake of examples.

2. From a command line, navigate to the workspace folder and clone the sample platform.

   git clone https://github.com/folio-org/stripes-sample-platform.git

3. Navigate into the command line and switch to the current updated branch of stripes-sample-platform:

   git checkout ramsons-yarnv1

4. Back in the Create a package.json file in your workspace folder, sibling to the stripes-sample-platform folder. Add these contents to the file:

   { "private": true, "workspaces": [ "*" ], "devDependencies": { "@folio/stripes-cli": "^3.2.0" } }

   
   Your project directory should now look like this:

   Open

   

    

5. Install the workspace by running the yarn command from the “FOLIO_Workspace” folder. Give the dependencies a few minutes to install.
   
   The install process creates a node_modules folder as well as a yarn.lock file in the “FOLIO_Workspace” folder.

6. Now the exciting part: Create a new FOLIO App by running the following command in the “FOLIO_Workspace” folder:

   Feel free to substitute the intended name of your app for “starter”.
   stripes-cli will ask for a brief description. Fill it in with “My First FOLIO App!” Just for example purposes.
   
   stripes-cli will clone an example repo to the folder and fill out the templated strings using your app’s name and the description that you provided. It will yarn install/update dependencies within the workspace as well.

   Now your workspace directory structure will look like this:

   Open

   

    

7. Within the stripes-sample-platform folder, open the stripes.config.js file. This configuration controls the build process. Look for the modules field. It contains only a single entry - "@folio/users": {}
   Add your UI module to this modules list like so:

    

8. Back at the command line, navigate to the stripes-sample-platform folder, and run the command:

   You’ll see console output that looks like the following. Notice the name of our module (ui-starter) shows up in the list!

   Eventually you’ll see something like

    

9. Open a web browser to localhost:3000
   The login page will appear. Ender diku_admin and admin for credentials.
   
   

    

10. The FOLIO Landing page will appear. You should see a link to our custom UI module in the Main navigation:
    
    

     

11. The title looks odd in the header, right? It’s actually rendering a key to a translation string. To fix this, you’ll need to navigate to the <your app>/translations folder and copy the en.json file, renaming the copy to en_US.json - or to whichever locale you set the FOLIO UI to. Exiting the serve command and re-running it should now display your module’s name up top!
    
    

     

12. The branch we switched stripes-sample-platform to a ‘training wheels’ branch to make this process quicker.
    If you’re developing your own backend module, you should definitely modify stripes.config.js to point to your locally running okapi instance (set the url under the okapi field - okapi: { 'url':'http://localhost:9130', 'tenant':'diku' })
    
    and apply your custom app’s permissions to your local okapi’s “diku_admin” user with the following command from the app’s directory:
    
    

    This will remove the need for the hasAllPerms: true (or the --hasAllPerms command-line flag.)
    The list of your custom app’s permissions can be found in the package.json . The process executed by yarn stripes app create filled in your custom module’s name into the baseline permissions.