Integrating with Rails

This page explains how to integrate Nebula with a Rails app.

:::tip This is a community-maintained document. Please ask the community if you have questions about this integration. You can also suggest improvements to make it better. :::

Requirements

This integration has been tested with the following:

Rails >= 6
Node >= 12.10
Webpacker >= 5

Instructions

To get started using Nebula with Rails, the following packages must be installed.

yarn add @onsonr/nebula copy-webpack-plugin

Importing the Default Theme

The next step is to import Nebula's default theme (stylesheet) in app/javascript/stylesheets/application.scss.

@import '@onsonr/nebula/dist/themes/light';
@import '@onsonr/nebula/dist/themes/dark'; // Optional dark theme

Fore more details about themes, please refer to Theme Basics.

Importing Required Scripts

After importing the theme, you'll need to import the JavaScript files for Nebula. Add the following code to app/javascript/packs/application.js.

import '../stylesheets/application.scss'
import { setBasePath, SlAlert, SlAnimation, SlButton, ... } from '@onsonr/nebula'

// ...

const rootUrl = document.currentScript.src.replace(/\/packs.*$/, '')

// Path to the assets folder (should be independent from the current script source path
// to work correctly in different environments)
setBasePath(rootUrl + '/packs/js/')

webpack Config

Next we need to add Nebula's assets to the final build output. To do this, modify config/webpack/environment.js to look like this.

const { environment } = require('@rails/webpacker');

// Nebula config
const path = require('path');
const CopyPlugin = require('copy-webpack-plugin');

// Add shoelace assets to webpack's build process
environment.plugins.append(
  'CopyPlugin',
  new CopyPlugin({
    patterns: [
      {
        from: path.resolve(__dirname, '../../node_modules/@onsonr/nebula/dist/assets'),
        to: path.resolve(__dirname, '../../public/packs/js/assets')
      }
    ]
  })
);

module.exports = environment;

Adding Pack Tags

The final step is to add the corresponding pack_tags to the page. You should have the following tags in the <head> section of app/views/layouts/application.html.erb.

<!doctype html>
<html>
  <head>
    <!-- ... -->

    <%= stylesheet_pack_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %> <%= javascript_pack_tag
    'application', 'data-turbolinks-track': 'reload' %>
  </head>
  <body>
    <%= yield %>
  </body>
</html>

Now you can start using Nebula components with Rails!

Additional Resources

There is a third-party example repo, courtesy of ParamagicDev available to help you get started.
If you would like to avoid repeating this process, check out the associated Railsbyte for Nebula.

3.2 KiB Raw Blame History