For Developers

Do you want to develop something? Great, below we curated a list of helpful guidelines to get you started. Feel free to contact the product team if something is missing or you have feedback.

    Installation

    yarn add @pxwlab/katana-snx
    
    npm install --save @pxwlab/katana-snx
    

    Package

    The package consists of the following:

    • dist/assets
      • all static assets like background-images, fonts and favicons live here
    • dist/katana-components.css
      • the stylesheet with relative imports that can be resolved by webpack
    • dist/katana-components.js
      • the react component library with all patterns
    • dist/katana-scripts.js
      • if you do not use the react components, this script file will provide all interactivity for the patterns
    • dist/sprite.svg
      • The svg-sprite with all svg icons

    Using the package with webpack

    ⚠️ Note: This is just a guideline. You may want to optimize your setup further to gain additional performance.

    You need to configure webpack to handle loading of the following files / formats:

    • CSS
    • images, fonts
    • SVGs (Optional)
    • JS

    Example entry file

    import '@pxwlab/katana-snx/katana-components.css'
    import '@pxwlab/katana-snx/katana-scripts.js'
    

    This is all you need to add in your entry file to have all styles and scripts loaded into your app. Now you need to configure webpack rules for the imports.


    Config rules

    Handling CSS

    {
      test: [/.css$/],
      use: [MiniCssExtractPlugin.loader, 'css-loader']
    },
    

    This will extract all css imports in your entry file.

    Handling static assets in CSS

    {
      test: /\.(ttf|eot|woff(2)?|jpeg|jpg|png)$/,
      use: [
        {
          loader: require.resolve('url-loader'),
          options: {
            limit: 8192,
            fallback: require.resolve('file-loader'),
            name: '[name]-[hash].[ext]',
            esModule: false
          }
        }
      ]
    }
    

    This will inline background-images and other assets into the generated css. Files bigger than 8kb will be loaded with file-loader. This means they will be copied into the dist folder and referenced via a hashed url to keep the generated css-file small.

    Handling the svg-sprite

      {
        test: /\.svg$/,
        loader: 'svg-inline-loader'
      },
    

    You can use svg-inline-loader to load the svg-sprite in the js file. You could then append it to the body:

    // index.js
    
    import spritesheet from '@pxwlab/katana-snx/sprite.svg'
    
    function svgSprite() {
      const element = document.createElement('div')
      element.style.position = 'absolute'
      element.style.zIndex = '-10000'
    
      element.innerHTML = spritesheet
    
      return element
    }
    
    document.body.appendChild(svgSprite())
    

    Alternatively you may load the spritesheet from a static path and reference it via the url:

    <svg><use xlink:href="/path/to/sprite.svg#icon-name"></use></svg>
    

    Here you need to manually copy the sprite from node_modules and also adjust all svg-icons in the markup to reference the sprite via url.


    Using react

    If you use the react component library you can omit the katana-scripts.js import in your entry file:

      import '@pxwlab/katana-snx/katana-components.css'
    - import '@pxwlab/katana-snx/katana-scripts.js'
    // ^ remove this line ^
    

    All other imports and webpack-loader-rules stay identical.

    You can now import the components from the main of the package (dist/katana-components.js), e.g.:

    import { Button } from '@pxwlab/katana-snx'
    
    export default () => (
      <Button onClick={() => console.log('Hello world!')}>Hello world</Button>
    )
    

    Static assets