inversify-react

Components and decorators to connect react with inversify.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
inversify-react
1.1.0a year ago7 years agoMinified + gzip package size for inversify-react in KB

Popular Searches

Readme

inversify-react
npm version npm peer dependency version npm peer dependency version --- Hooks and decorators for InversifyJS + React. --- Table of Contents 
+ [useInjection](#useinjection)
+ [useOptionalInjection](#useoptionalinjection)
+ [useContainer](#usecontainer)
+ [useAllInjections](#useallinjections)
+ [@resolve](#-resolve)
+ [@resolve.optional](#-resolveoptional)

Motivation

TL;DR:
  1. InversifyJS, as IoC container, is great for automatic DI
  1. use it also in React

Installation

  • npm install --save inversify-react
  • yarn add inversify-react
...on top of your project with other modules already installed and configured ``` react inversify reflect-metadata ``` Keep in mind that Inversify uses decorators, which requires some setup for your build process. Read more about decorators:
  • https://github.com/inversify/InversifyJS#installation
  • https://github.com/loganfsmyth/babel-plugin-transform-decorators-legacy
  • https://www.typescriptlang.org/docs/handbook/decorators.html
inversify-react also uses decorators, but only when used in Class Components.

Usage overview

Usage is pretty similar to React Context.
  1. Wrap React component tree with Provider and Container from inversify-react – just like React Context.Provider
```js
import { Provider } from 'inversify-react';
...
<Provider container={myContainer}>
...
</Provider>
```
  1. Use dependencies from that container in child components
```ts
import { resolve, useInjection } from 'inversify-react';
...
// In functional component – via hooks
const ChildComponent: React.FC = () => {
const foo = useInjection(Foo);
...
};
// or in class component – via decorated fields
class ChildComponent extends React.Component {
@resolve
private readonly foo: Foo;
...
}
```

Provider

```js 
...
```
  • can automatically establish hierarchy of containers in React tree when you use multiple Providers (e.g. in a big modular app)
  • props:
* `container` - container instance or container factory function
* `standalone` - (optional prop, `false` by default) whether to skip [hierarchy of containers](https://github.com/inversify/InversifyJS/blob/master/wiki/hierarchical_di.md). Could be useful if you already control container hierarchy and would like to ignore React-tree-based hierarchy.
```ts import as React from 'react'; import { Container } from 'inversify'; import { Provider } from 'inversify-react'; // in functional component const AppOrModuleRoot: React.FC = () => { 
return (
<Provider container={() => {
const container = new Container();
container.bind(Foo).toSelf();
container.bind(Bar).toSelf();
return container;
}}>
{/*...children...*/}
</Provider>
);
}; // or class component class AppOrModuleRoot extends React.Component { 
// you can create and store container instance explicitly,
// or use factory function like in functional component example above
private readonly container = new Container();
constructor(props: {}, context: {}) {
super(props, context);
const { container } = this;
container.bind(Foo).toSelf();
container.bind(Bar).toSelf();
}
render() {
return (
<Provider container={this.container}>
{/*...children...*/}
</Provider>
);
}
} ```

React hooks

useInjection

```ts const foo = useInjection(Foo); ```

useOptionalInjection

```ts // e.g. Foo and Bar are not bound const foo = useOptionalInjection(Foo); // will return undefined // or const bar = useOptionalInjection(Bar, () => 'defaultBar'); // will return 'defaultBar' ```
  • default value can be defined via lazy resolving function (2nd argument)
```ts
const foo = useOptionalInjection(Foo, () => myDefault);
// foo === myDefault
//   ^ Foo | typeof myDefault
```
That function conveniently receives container as argument, so you could instantiate your *default* using container (e.g. if it has dependencies)
```ts
const foo = useOptionalInjection(Foo, container => container.resolve(X));
```

useContainer

```ts const container = useContainer(); // or const foo = useContainer(container => container.resolve(Foo)); ```
  • low-level hook, resolves container itself
  • has overload with callback to immediately resolve value from container, so could be used for more exotic API, e.g. named or tagged bindings

useAllInjections

```ts const bars = useAllInjections(Bar); ```` For more examples, please refer to tests: test/hooks.tsx

React component decorators (for classes)

@resolve

```ts @resolve foo: Foo; // or strict and semantic, see tips below @resolve private readonly foo!: Foo; ```
  • resolves service from container
  • requires reflect-metadata and emitDecoratorMetadata
```ts // or pass service identifier explicitly // e.g. if you deal with interfaces and/or don't want to use field type (via reflect-metadata) @resolve(IFooServiceId) private readonly foo!: IFoo; ```

@resolve.optional

```ts @resolve.optional private readonly foo?: Foo; ```
  • tries to resolve service from container, but returns undefined if service cannot be obtained
  • requires reflect-metadata and emitDecoratorMetadata
@resolve.optional(serviceId, defaultValue?)
  • obtains service from container passed down in the React tree, returns defaultValue if service cannot be obtained
```ts class ChildComponent extends React.Component { 
@resolve
private readonly foo!: Foo;
@resolve(Bar)
private readonly bar!: Bar;
@resolve.optional(Baz)
private readonly opt?: Baz;
...
} // you can also use dependency in constructor, // just don't forget to call super with context // @see https://github.com/facebook/react/issues/13944 constructor(props: {}, context: {}) { 
super(props, context);
console.log(this.foo.name);
} ```

@resolve.all

```ts @resolve.all('Foo') private readonly foo?: Foo; ```
  • tries to resolve all services from container, fails if no services are bound to given service identifier
  • requires reflect-metadata and emitDecoratorMetadata, but cannot be used without explicitly specifying service identifier
@resolve.all(serviceId)
  • obtains services from container passed down in the React tree
```ts class ChildComponent extends React.Component { 
@resolve.all(Baz)
private readonly opt?: Baz[];
...
} ```

@resolve.optional.all

```ts @resolve.optional.all('Foo') private readonly foo?: Foo; ```
  • tries to resolve all services from container, returns empty array if none are registered
  • requires reflect-metadata and emitDecoratorMetadata, but cannot be used without explicitly specifying service identifier
@resolve.optional.all(serviceId)
  • obtains services from container passed down in the React tree
```ts class ChildComponent extends React.Component { 
@resolve.optional.all(Baz)
private readonly opt?: Baz[];
...
} ```

Notes, tips

  1. \TypeScript tip\] private readonly for @resolve-ed fields is not required, but technically it's more accurate, gives better semantics and all.
  1. \TypeScript tip\] ! for @resolve-ed fields is needed for strictPropertyInitialization / strict flags (which are highly recommended).
  1. \InversifyJS tip\] If you're binding against interface, then it might be more comfortable to collocate service identifier and type. With typed service identifier you get better type inference and less imports. Way better DX compared to using strings as identifiers.
```ts
export interface IFoo {
// ...
}
export namespace IFoo {
export const $: interfaces.ServiceIdentifier<IFoo> = Symbol('IFoo');
}
```
```ts
container.bind(IFoo.$).to(...);
//            ^ no need to specify generic type,
//              type gets inferred from explicit service identifier
```
```ts
// in constructor injections (not in React Components, but in services/stores/etc)
constructor(@inject(IFoo.$) foo: IFoo)
// in React Class component
@resolve(IFoo.$)
private readonly foo!: IFoo; // less imports and less chance of mix-up
// in functional component
const foo = useInjection(IFoo.$); // inferred as IFoo
```