next-image-element

🖼️ Import paths or React elements from images in Next.js. 📦

import { element as LogoSVG } from "./logo.svg";
import photoImagePath from "./photo.jpg";

export default (props) => (
  <div>
    <LogoSVG width="230" height="140" fill={props.color} />
    <img src={photoImagePath} alt="flower" />
  </div>
);

Table of Contents
Features
Quick Start
Usage
Options
Recipes
- Enables type checking in TypeScript
- Uses in other libraries such as Storybook
Contributing to next-image-element
License

Features

FEATURES	WHAT YOU CAN DO
⚛️ Designed for JSX	Import images as React element like `<MySVG fill={color} />`
🎨 Designed for CSS	Import images as some URL in not JavaScript files
✨ Exported as plain image	Import image paths or as inline image (Base64)
🎩 Type Safe	You can use with TypeScript
🔧 Built for Next.js	It's very easy to setup

Quick Start

Requirements

npm or Yarn
Next.js 5.0.0 or higher

Installation

$ npm install -D next-image-element

If you are using Yarn, use the following command.

$ yarn add -D next-image-element

Setup

Firstly setup your Next.js settings.

// next.config.js
const withImageElement = require("next-image-element");

module.exports = withImageElement();

All you need is the above!

Usage

This package depends on react-image-element-loader, for more detail, see here.

You can import file path or React element from images. It's possible to pass props such as HTMLAttributes, but src will be ignored.

import { element as LogoSVG } from "./logo.svg";
import photoImagePath from "./photo.jpg";

export default (props) => (
  <div>
    <LogoSVG width="230" height="140" fill={props.color} />
    <img src={photoImagePath} alt="flower" />
  </div>
);

Also when you import images from not JavaScript files such as CSS, next-image-element imports them as same as using default export, so it will be actual URL or inline image (Base64).

.box {
  background-image: url("./icon.png");
}

next-image-element supports PNG (.png), JPEG (.jpg), GIF (.gif), and SVG (.svg).

Options

`sizeLimit`

Type: Number Default: undefined

This option is to specify the maximum size of image file in bytes.

If an image is greater than the limit or sizeLimit option specified undefined, path will be an actual URL. In that case, file-loader will be used and all query parameters are passed to it. If an image is smaller than the limit, path will be Base64 encoded URL.

module.exports = withImageElement({
  imageElementOptions: {
    sizeLimit: 10240, // 10kB
  },
});

The limit can be specified via loader options and defaults to no limit.

`publicPath`

Type: String Default: "/_next/static/images/"

This option is to specify published image path used as actual URL. When you use next-image-element in Next.js projects, you should start with "/_next/static/" .

module.exports = withImageElement({
  imageElementOptions: {
    publicPath: "/static/images/",
  },
});

`outputPath`

Type: String or Function Default: (isServer) => `${isServer ? "../" : ""}static/images/

This option is to specify output image path. If you give string as this option, next-image-element will just use it. If you give function as this option, next-image-element will call it with isServer boolean value as the first argument, so you have to give function which returns string in this case.

module.exports = withImageElement({
  imageElementOptions: {
    outputPath: "/static/images/",
  },
});

`outputFileNamePattern`

Type: String Default: "[name]-[hash].[ext]"

This option is to specify a pattern of images' file name. For more detail, please check this.

module.exports = withImageElement({
  imageElementOptions: {
    outputFileNamePattern: "[hash].[ext]",
  },
});

Recipes

For more detail, see here.

Enables type checking in TypeScript

If you want to enable type checking in TypeScript for images, you should add the following to next-env.d.ts file.

/// <reference types="next" />
/// <reference types="next/types/global" />

+ /// <reference types="next-image-element" />

Uses in other libraries such as Storybook

Libraries such as Storybook outside Next.js does not load _next directory automatically, but next-image-element uses _next as published image path by default. So if you change the public path, the library can load images.

// storybook/webpack.config.js
module.exports = async ({ config }) => {
  withImageElement({ imageElementOptions: { publicPath: "/static/images/" }}).webpack(config, { isServer: false });

  return config;
};

Contributing to next-image-element

Bug reports and pull requests are welcome on GitHub at https://github.com/jagaapple/next-image-element. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Please read Contributing Guidelines before development and contributing.

License

The library is available as open source under the terms of the MIT License.

p-chan / next-image-element Goto Github PK