Installation
-Like most Dependency Injection frameworks, Obsidian uses automatic code generation to create the bindings necessary for resolving dependencies. This approach helps reduce the amount of boilerplate code required by developers. Obsidian relies on Babel for code generation, so you'll need to have Babel configured in your project.
-If your project uses either Vite or Create React App, please refer to the Integration with third-party front-end environments section before following the steps below.
Installing Obsidian is a straightforward process that involves adding the package to your project, enabling TypeScript decorators, and adding Obsidian's transformer to your build system, either Babel or SWC. Let's go through the steps.
1. Install Obsidian​
-npm install react-obsidian
Install the package using your preferred package manager:
+- Yarn
- NPM
yarn add react-obsidian
npm install react-obsidian
2. Install Reflect-metadata​
-First, install and enable the reflect-metadata polyfill.
-npm install reflect-metadata
Then, add the following line to the top of your application's entry point (usually index.js or index.ts):
+First, install the reflect-metadata package:
- Yarn
- NPM
yarn add reflect-metadata
npm install reflect-metadata
Then, enable the reflect-metadata polyfill by adding the following line to the top of your application's entry point (usually index.js or index.ts):
import 'reflect-metadata';
3. Enable experimental decorators​
Obsidian uses the Decorators feature whose proposal is at stage 3.
Add the following options to your tsconfig.json file.
{
"compilerOptions": {
"experimentalDecorators": true,
"emitDecoratorMetadata": true
}
}
4. Add the required Babel plugins​
-BabelJS is a JavaScript compiler that is used to transpile modern JavaScript code into code that is compatible with older browsers. Obsidian uses a Babel transformer to generate code that is used to resolve dependencies.
-4.1. Install the required Babel plugins​
-You will need to install these plugins if you don't have them already:
-- Yarn
- NPM
yarn add @babel/plugin-proposal-decorators @babel/plugin-transform-class-properties babel-plugin-parameter-decorator @babel/core @babel/preset-env @babel/preset-typescript
npm install @babel/plugin-proposal-decorators @babel/plugin-transform-class-properties babel-plugin-parameter-decorator @babel/core @babel/preset-env
If this is your first time using Babel, you will also need to install Babel's core packages:
-- Yarn
- NPM
yarn add @babel/core @babel/preset-env @babel/preset-typescript
npm install @babel/core @babel/preset-env @babel/preset-typescript
4.2. Update your Babel configuration​
-Add the transformer and the required plugins to the list of plugins in your babel.config.js file or .babelrc file:
module.exports = {
presets: [
'module:metro-react-native-babel-preset',
+ ['@babel/preset-typescript', {'onlyRemoveTypeImports': true}]
],
plugins: [
+ react-obsidian/dist/transformers/babel-plugin-obsidian,
+ ['@babel/plugin-proposal-decorators', {legacy: true}],
+ '@babel/plugin-transform-class-properties',
+ 'babel-plugin-parameter-decorator'
]
};
4. Add Obsidian's transformer​
+Like most Dependency Injection frameworks, Obsidian uses automatic code generation to create the bindings necessary for resolving dependencies. This approach helps reduce the amount of boilerplate code required by developers.
+- Babel (React Native or Vite + Babel)
- SWC (Vite + SWC)
Install the required Babel plugins​
You will need to install these plugins if you don't have them already:
- Yarn
- NPM
yarn add @babel/plugin-proposal-decorators @babel/plugin-transform-class-properties babel-plugin-parameter-decorator @babel/core @babel/preset-env @babel/preset-typescript
npm install @babel/plugin-proposal-decorators @babel/plugin-transform-class-properties babel-plugin-parameter-decorator @babel/core @babel/preset-env
If this is your first time using Babel, you will also need to install Babel's core packages:
- Yarn
- NPM
yarn add @babel/core @babel/preset-env @babel/preset-typescript
npm install @babel/core @babel/preset-env @babel/preset-typescript
Update your Babel configuration​
Add the transformer and the required plugins to the list of plugins in your babel.config.js file or .babelrc file:
module.exports = {
presets: [
'module:metro-react-native-babel-preset',
+ ['@babel/preset-typescript', {'onlyRemoveTypeImports': true}]
],
plugins: [
+ react-obsidian/dist/transformers/babel-plugin-obsidian,
+ ['@babel/plugin-proposal-decorators', {legacy: true}],
+ '@babel/plugin-transform-class-properties',
+ 'babel-plugin-parameter-decorator'
]
};
Install the required dependencies​
- Yarn
- NPM
yarn add -D unplugin-swc @swc/core
npm install -D unplugin-swc @swc/core
Update your Vite configuration​
Add the transformer to the list of plugins in your vite.config.js file:
import { defineConfig } from 'vite';
import swc from 'unplugin-swc';
import obsidian from 'swc-plugin-obsidian';
// https://vitejs.dev/config/
export default defineConfig({
plugins: [
swc.vite({
jsc: {
parser: {
syntax: "typescript",
decorators: true,
},
experimental: {
runPluginFirst: true,
plugins: [obsidian()],
},
},
}),
],
});
5. Optional - Add Obsidian's ESLint plugin​
-Obsidian provides an ESLint plugin that can help you find errors in your code related to dependency injection. See the ESLint plugin documentation for more information.
-Integration with third-party front-end environments​
-Vite​
-Vite provides a modern development environment for React application. It boasts an extremely fast development server that uses Hot Module Replacement (HMR) to enable near-instant startup time.
-When integrating Obsidian in a Vite application, follow steps 1-3 and step 4.1 that are listed above. Instead of step 4.2, we'll configure Obsidian't Babel transformer in Vite's vite.config.js file:
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
// https://vitejs.dev/config/
export default defineConfig({
plugins: [
react({
babel: {
plugins: [
'react-obsidian/dist/transformers/babel-plugin-obsidian',
['@babel/plugin-proposal-decorators', { legacy: true }],
],
},
}),
],
});
Create React App​
-Create React App (CRA) is a popular tool for getting started with React. It provides a pre-configured development environment that is ready to use out of the box.
-When integrating Obsidian in a CRA application, follow steps 1-4 that are listed above. Since CRA doesn't allow you to configure Babel directly, we'll need to install two additional packages:
--
-
- react-app-rewired. This package allows you to customize CRA scripts without ejecting. -
- customize-cra. This package provides a set of utilities that can be used to customize CRA configurations. It has to be used instead of the default
react-scriptspackage.
-
Install the required packages and modify the default scripts​
-{
"devDependencies": {
+ "customize-cra": "1.0.0",
+ "react-app-rewired": "2.2.1"
},
"scripts": {
+ "start": "react-app-rewired start",
+ "build": "react-app-rewired build",
+ "test": "npx jest",
- "start": "react-scripts start",
- "build": "react-scripts build",
- "test": "react-scripts test --env=jsdom",
}
}
Configure Babel​
-Create a config-overrides.js file in the root of your project and add the following code to it:
const { useBabelRc, override } = require('customize-cra');
module.exports = override(useBabelRc());