|
1 | | -# ng2react Documentation |
| 1 | +# AngularJS to React - VSCode Extension |
2 | 2 |
|
3 | | -ng2react is a tool that converts AngularJS components to React components using the OpenAI API. It consists of an IDE plugin, a core library, a CLI, and a feedback API. |
| 3 | +An extension for converting AngularJS to React, leveraging OpenAI's GPT API. |
4 | 4 |
|
5 | | - |
| 5 | +[View in marketplace](https://marketplace.visualstudio.com/items?itemName=maxbilbow.ng2react-vscode&ssr=false#overview) |
6 | 6 |
|
7 | 7 | ## Features |
8 | 8 |
|
9 | | -- **Convert AngularJS Components**: The plugin allows users to easily convert AngularJS components to React components by sending the components to the ng2react core library, which uses TypeScript for parsing AngularJS components and the OpenAI API to generate the React version of the component. |
| 9 | +- **Convert AngularJS Components**: The plugin allows users to easily convert AngularJS components to React components by sending the components to the ng2react core library, which uses TypeScript for parsing AngularJS components and the OpenAI API to generate the React version of the component. |
10 | 10 |
|
11 | | -- **Feedback Submission**: The plugin enables users to submit feedback about the conversion results directly from the IDE. This feedback helps the ng2react team to identify areas for improvement and ensure the tool continues to meet user needs. |
| 11 | + |
12 | 12 |
|
13 | | -- **User-friendly Interface**: The ng2react IDE plugin is designed with usability in mind, providing a seamless experience for developers working with both AngularJS and React codebases. |
| 13 | +## Requirements |
14 | 14 |
|
15 | | -## IDE Plugin |
| 15 | +- **OpenAI API Key**: The plugin requires an OpenAI API key to be set in the `ng2react.openai.apiKey` setting. You can get an API key by signing up for the [OpenAI API](https://beta.openai.com/). |
16 | 16 |
|
17 | | -The ng2react IDE plugin is an essential component of the ng2react software system. It integrates with the user's development environment and provides an interface for converting AngularJS components to React components using the core library. The plugin also enables users to submit feedback about the conversion results directly to the feedback API. |
| 17 | +## Configuration |
18 | 18 |
|
19 | | -Two types of IDE plugins are supported: |
| 19 | +### OpenAI Settings |
20 | 20 |
|
21 | | -- **NodeJS Based IDE Plugins**: These plugins are built for IDEs that support NodeJS plugins, such as VSCode and Atom. They can use @ng2react/core directly. |
22 | | -- **Other IDE Plugins**: These plugins are built for IDEs that do not support NodeJS plugins, such as IntelliJ and Eclipse. They can be immpemented via the @ng2react/cli. |
| 21 | +- `ng2react.openai.apiKey`: The OpenAI API key to use for generating React components from AngularJS components. |
| 22 | +- `ng2react.openai.model`: The OpenAI engine to use for generating React components from AngularJS components. Defaults to `gpt-4`. |
| 23 | +- `ng2react.openai.temperature`: The OpenAI temperature to use for generating React components from AngularJS components. Defaults to `0.2`. |
| 24 | +- `ng2react.openai.orginization`: An optional organization ID assiciated with your OpenAI account. |
23 | 25 |
|
24 | | - |
| 26 | +### Project Settings |
25 | 27 |
|
26 | | -### NodeJS Based IDE Plugin |
| 28 | +- `ng2react.angularRoot`: The source root of your AngularJS code. Defaults to `src`. |
| 29 | +- `ng2react.reactRoot`: The source root of your AngularJS code. Defaults to `src`. |
| 30 | +- `ng2react.testRoot`: The source root where React unit tests should be generated |
| 31 | +- `ng2react.testFileSuffix`: Default test file suffix. Defaults to `.test.tsx`. |
| 32 | +- `ng2react.enabled`: Whether or not the extension is enabled. Defaults to `auto`. |
| 33 | +- `ng2react.sandboxMode`: Whether or not to run the extension in sandbox mode. Defaults to `false`. |
27 | 34 |
|
28 | | - |
| 35 | +## Known Issues |
29 | 36 |
|
30 | | -### Other IDE Plugins |
| 37 | +This is an early alpha release of the extension. There are many known issues and limitations, including: |
31 | 38 |
|
32 | | - |
| 39 | +- AI Generated Code: The generated code is not guaranteed to be correct. It is generated by an AI model and may contain bugs. |
| 40 | +- Limited Support: The extension currently only supports converting AngularJS components to React components. It does not support converting AngularJS services, directives, or other types of AngularJS code. |
33 | 41 |
|
34 | | -## Ng2React |
| 42 | +## Wrapping React Components |
35 | 43 |
|
36 | | -### Core |
| 44 | +A [support library is availabe for wrapping React components in AngularJS](https://www.npmjs.com/package/@ng2react/support)components. This library may not have long-term support, but you are free to use, fork, or copy whatever you like from it. |
37 | 45 |
|
38 | | -The ng2react core library is responsible for converting AngularJS components to React components. It leverages the TypeScript AST for parsing AngularJS components and uses the OpenAI API to generate the corresponding React components. |
| 46 | +### Installation |
39 | 47 |
|
40 | | - |
| 48 | +```bash |
| 49 | +npm install --save @ng2react/support |
| 50 | +``` |
41 | 51 |
|
42 | | -### CLI |
| 52 | +### Usage |
43 | 53 |
|
44 | | -The ng2react CLI is a command-line interface that enables developers to convert AngularJS components to React components without using an IDE plugin. It provides a convenient way for developers to integrate the ng2react functionality into their existing workflows and tooling. |
| 54 | +#### Convert your AngularJS component or directive to React |
45 | 55 |
|
46 | | - |
| 56 | +You may do this manually or with the help of the [ng2react vscode extension](https://marketplace.visualstudio.com/items?itemName=maxbilbow.ng2react-vscode) |
47 | 57 |
|
48 | | -### Feedback API |
| 58 | +```jsx |
| 59 | +// React Component |
| 60 | +import React, { useState } from "react"; |
| 61 | +import { useService, NgTranslate } from "@ng2react/support"; |
49 | 62 |
|
50 | | -The feedback API allows users to submit feedback about the conversion results directly from the ng2react IDE plugin. It stores the feedback data in a database for later analysis and review by the ng2react team. This feedback is essential for identifying areas for improvement and ensuring the tool continues to meet user needs. |
| 63 | +const MyReactComponent = ({ title, myController }) => { |
| 64 | + const myService = useService("myService"); |
| 65 | + const [state, setState] = useState(myService.getState()); |
| 66 | + return ( |
| 67 | + <> |
| 68 | + <h1>{title}</h1> |
| 69 | + <p>{state}</p> |
| 70 | + <p> |
| 71 | + <NgTranslate |
| 72 | + id={"TRANLATED_TEXT_ID"} |
| 73 | + substitutions={myController.getValue()} |
| 74 | + /> |
| 75 | + </p> |
| 76 | + </> |
| 77 | + ); |
| 78 | +}; |
| 79 | +``` |
51 | 80 |
|
52 | | - |
| 81 | +#### Wrap your React component |
53 | 82 |
|
54 | | -### Feedback Analysis Client |
| 83 | +```js |
| 84 | +// AngularJS Component |
| 85 | +import * as angular from "angular"; |
| 86 | +import { angularize } from "@ng2react/support"; |
| 87 | +import { MyReactComponent } from "./MyReactComponent.jsx"; |
55 | 88 |
|
56 | | -The feedback analysis client is a tool used by the ng2react team to review and analyze the feedback submitted by users. It provides an interface for browsing, filtering, and analyzing feedback data stored in the feedback database. This tool helps the team identify trends, common issues, and areas for improvement in the ng2react system. |
57 | | - |
58 | | -## Existing Plugins |
59 | | - |
60 | | -### VSCode |
61 | | - |
62 | | - |
| 89 | +const myApp = angular.module("myApp", []); |
| 90 | +angularize(MyReactElement, { |
| 91 | + module: myApp, |
| 92 | + name: "myAngularComponent", |
| 93 | + bindings: { |
| 94 | + title: "@", |
| 95 | + }, |
| 96 | + require: { |
| 97 | + myController: "^myController", |
| 98 | + }, |
| 99 | + replace: true, |
| 100 | +}); |
| 101 | +``` |
0 commit comments