@niiwin/core v3.2.1

Niiwin

This repo contains the source code for the Niiwin Rails engine and npm package. Find out more about Niiwin at https://niiwin.app

Getting started for Niiwin Core Developers

Follow these steps if you are a Niiwin Core Developer and you work on the Niiwin RubyGem, npm package, or dev toolchain:

Prerequisites

You'll need the following installed to continue setting up your development environment:

• A Ruby version manager/switcher (rbenv, rvm, chruby, asdf, etc.)
• Node.js (14.21.3+)
• Yarn (1.22.0+)
• Postgresql (9.6+)
• Redis (6+)
• Optional: The 1Password CLI1

Install Ruby

This assumes you have rbenv installed, though another Ruby version manager will also work.

• Check that the required Ruby version 3.2.2 is installed: rbenv versions
• Install it if it's not installed yet: rbenv install 3.2.2
• Set global Ruby version to 3.2.2: rbenv global 3.2.2

Set up the Niiwin gem repo

Clone the repo git clone git@github.com:animikii/niiwin.git

Make sure you are in the Niiwin gem root directory, then install the dependencies:

bundle install
yarn install
yarn build

Use your local gem source in a generated Niiwin App

You can use your local gem source in a Niiwin App that was generated through the docker based process. Please note that the actual app generation doesn't use your local gem source. If you are looking for a way to generate a new Niiwin app using your local gem source, please see further down in this document.

Create a new app using the steps from the app developer guide.

Once the script finishes successfully, Ctrl + C to stop the containers. We currently only support core development on bare metal, so you can remove or ignore the containers.

The node modules were installed by the container which is running linux, so we have to remove and reinstall them.

rm -rf node_modules
yarn install

Update the Gemfile to make the niiwin gem point to your local niiwin, instead of the Gemfury release.

gem "niiwin", "3.2.0", path: "/path/to/your/niiwin"

Tip: You could also export an environment variable in your .bashrc or .zshrc and then reference that directly, if it seems easier.

gem "niiwin", "3.2.0", path: ENV["NIIWIN_GEM_SOURCE"]

Next, install the ruby dependencies.

bundle install

Update the .env file with your postgres and redis connection information, then set up the database with:

bin/rails db:setup

Now you are ready to start the server.

source .env && ./bin/dev

In a browser, visit http://localhost:8000, and use the "Dev Login" button at the bottom of the page to choose a role and log in.

Now you can start working on the new Niiwin App, or on the Niiwin Engine itself.

NOTE: If you have more than one niiwin app running on your machine set up a different REDIS_URL for each running app, otherwise apps will place jobs on the same redis queue. You will also have to set up different ports in your .env file.

Generate a new Niiwin app using your local gem source

This section describes how you can generate a new Niiwin app based on your local gem source. This is in contrast to the approach described above where the app is generated from the published starter template.

When you make changes to the ruby gem you may want to test them locally, before submitting a PR. To create a new app that references your local ruby gem:

• Create a new rails application with the latest version used in the gem. Look for the rails gem version in the Gemfile.lock.

rails _7.2.1_ new my_test_app --database=postgresql --skip-spring --skip-turbolinks --javascript=esbuild
cd my_test_app
echo "gem \"niiwin\", path: \"/path/to/your/niiwin\"" >> Gemfile
bundle install
bin/rails generate niiwin:install

Optional Tooling

pre-commit

If you would like to automatically fix standard-rb warnings before committing, install the pre-commit tool.

pip install pre-commit

Note re: git history in test_app

For test app commits before Jan 24th, 2025 the file path displayed in the Github web UI will be incorrect. The path will start with "test" instead of "test_app/test". This is due to the fact that the test repo used to live in its own repository and was merged into the main repo in January 2025. See video in NI-114 for details.