React component boilerplate

This is simple boilerplate project for building React component library for NPM. It is suitable for building of any type of UI component or library. The project/source code contains two separated phases for development. A one of live development and other for lib-based code.

How it is structured

As is described above the code is structured in two separated phases:

• The first is responsible to build component lib (production-ready) code for NPM
• The second phase is responsible to build development (Demo) app with HMR.

Getting started

Follow these steps to get started developing component library.

$ git clone [email protected]:sportal-media-platform/widget-starter-kit.git <my-project-name>
$ cd <my-project-name>

When that's done, install the project dependencies. It is recommended that you use Yarn for deterministic dependency management, but npm install will suffice.

$ yarn  # Install project dependencies (or `npm install`)

After completing that you are ready to do that

• $ rm -rf .git
• $ git init
• $ git add .
• $ git commit -m "Init project"

When you completed development

• $ npm publish --access restricted

Project Structure

The project structure presented in this boilerplate is fractal, where functionality is grouped primarily by feature rather than file type. This structure is only meant to serve as a guide, it is by no means prescriptive. That said, it aims to represent generally accepted guidelines and patterns for building scalable applications. If you wish to read more about this pattern, please check out this awesome writeup by Justin Greenberg.

.
├── build                            # All build-related code
├── dist                             # The all production-ready code 
├── lib                              # The library source code localization
├── design                           # Static folder where is stored the design (not imported anywhere in source code)
├── src                              # Application source code
│   ├── dev                          # Application bootstrap and rendering
│       ├── Main.jsx                 # The entry point of App (bootstraping component)
│       ├── Index.html               # Static HTML template (It is using only in dev mode ) 
│   ├── lib                          # Application widget where will live
|       ├── components               # The all components where will be stored
|       ├── design                   # The all design mock-ups where will be stored
|       ├── index.jsx                # The entry point of widget
|       ├── package-lib.json         # The schema of package.json for the component 
|       ├── README.md                # Description about how to use it
|       ├── LICENSE.md               # The license requirements
│   ├── styles                       # Application styles where will live
│   ├── locales                      # The all translation keys will live there
│       ├── locales.js                 # An entry point of the all locales
└── tests                            # Unit tests

Additional configuration information

    1. webpack.lib.config.js 
    -- npm command  - npm run build:lib
    -- yarn command - yarn run build:lib
    
    Contains configuration connected with the library build process of the widget
    it requires the given files/folders to exist under this path: widget-starter-kit/src/lib
    
    - README.md, LICENSE.md, design, package-lib.json
    
    2. webpack.prod.config.js
    -- npm run command  - npm run build:prod
    -- yarn run command - yarn run build:prod
    
    Contains configration connected with the production build process of the widget and also
    configuration required for the local run of the project.
    
    3. project.config.js
    - Contains configuration variables used by the webpack.lib.config.js and webpack.prod.config.js.
    IMPORTANT VARIABLES:
    selector - This should be setup when creating a new widget, example: 
    
    [data-widgetId="widget-<Widget Name>"]
    
    Delimeter used for the widget name: '-'

    portDEV - The default port used is 8000, this can be changed to whatever you want. 
    NB! If the port was changed from the default one (8000) always put the default value back before pushing any changes.

Creating different components

    When creating components please follow the given rules.
    1. There should be one MAIN component that (if required) will be making the NETWORK REQUESTS towards the respected API.
    2. The MAIN component can call other components by passing the needed data (if required) for those components to be able
    to create the representation.
    
    The idea behid these two simple rules is to keep the components creating the view, logically separated from the 
    data generating/NETWORK REQUESTING MAIN component. This way unit tests can be easily created for all of the sub-components

Bind the widget to HTML DOM

You can bind the widget to the HTML DOM by two ways:

• Bind the widget without initial options. The required attribute here is "data-widgetId"

    <div data-widgetId="widget-name"></div>

• Bind the widget with initial options. The all available options can be seen below

    <div data-widgetId="widget-name" data-options='{...}'></div>

• The optional "data-options" attribute:

    {
        int playerId: 1,      // Unique identifier of the resource.
        strin lang: 'en',    // the language in format like: en, bg, ru and etc.
        string theme: '',    // Brand theme 
        string expand: null, // Specifies additional information to include with the Team response
    }

Running the Project

After completing the installation step, you're ready to start the project!

$ yarn run start:dev  # Start the development server (or `npm run start:dev`)

While developing, you will probably rely mostly on yarn run start:dev; however, there are additional scripts at your disposal:

|yarn <script> |Description| |-------------------|-----------| |start:dev |Serves your app with HMR at http://localhost:8000| |build:lib |Builds library widget component to ./lib folder| |build:stage |TBD: Builds completely production-ready ReactJS application to ./dist folder| |build:prod |Builds completely production-ready ReactJS application to ./dist folder| |test |Not ready yet. See testing| |test:watch |Runs test in watch mode to re-run tests when changed| |test:prod |Runs production-ready application to ./dist folder at: http://localhost:8080|

Testing

To add a unit test, create a .spec.js file anywhere inside of ./tests. // TBD

Building for Production

Out of the box, this widget is deployable by serving the ./dist folder generated by yarn build:prod.