Skip to content

Commit d1f8090

Browse files
maxbilbowmaxbilbow
committed
Additional docs
1 parent 7a11982 commit d1f8090

7 files changed

+190
-5
lines changed

‎.readthedocs.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ version: 2
99
build:
1010
os: ubuntu-22.04
1111
tools:
12-
python: "3.11"
12+
python: "3.9"
1313

1414
mkdocs:
1515
configuration: mkdocs.yml

‎docs/VSCode.md

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# AngularJS to React - VSCode Extension
2+
3+
An experimental extension for converting AngularJS to React, leveraging OpenAI's GPT API.
4+
5+
[View in marketplace](https://marketplace.visualstudio.com/items?itemName=maxbilbow.ng2react-vscode&ssr=false#overview)
6+
7+
## Features
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.
10+
11+
![Component Conversion](images/todolist-conversion-example.png)
12+
13+
## Requirements
14+
15+
- **OpenAI API Key**: The plugin requires an OpenAI API key to be set in the `ng2react.apiKey` setting. You can get an API key by signing up for the [OpenAI API](https://beta.openai.com/).
16+
17+
## Extension Settings
18+
19+
This extension contributes the following settings:
20+
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.
25+
- `ng2react.angularRoot`: The source root of your AngularJS code. Defaults to `src`.
26+
- `ng2react.reactRoot`: The source root of your AngularJS code. Defaults to `src`.
27+
- `ng2react.testRoot`: The source root where React unit tests should be generated
28+
- `ng2react.testFileSuffix`: Default test file suffix. Defaults to `.test.tsx`.
29+
- `ng2react.enabled`: Whether or not the extension is enabled. Defaults to `auto`.
30+
- `ng2react.sandboxMode`: Whether or not to run the extension in sandbox mode. Defaults to `false`.
31+
32+
## Known Issues
33+
34+
This is an early alpha release of the extension. There are many known issues and limitations, including:
35+
36+
- AI Generated Code: The generated code is not guaranteed to be correct. It is generated by an AI model and may contain bugs.
37+
- 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.
38+
39+
## Wrapping React Components
40+
41+
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.
42+
43+
### Installation
44+
45+
```bash
46+
npm install --save @ng2react/support
47+
```
48+
49+
### Usage
50+
51+
#### Convert your AngularJS component or directive to React
52+
53+
You may do this manually or with the help of the [ng2react vscode extension](https://marketplace.visualstudio.com/items?itemName=maxbilbow.ng2react-vscode)
54+
55+
```jsx
56+
// React Component
57+
import React, { useState } from 'react';
58+
import { useService, NgTranslate } from '@ng2react/support';
59+
60+
const MyReactComponent = ({ title, myController }) => {
61+
const myService = useService('myService');
62+
const [state, setState] = useState(myService.getState());
63+
return (
64+
<>
65+
<h1>{title}</h1>
66+
<p>{state}</p>
67+
<p>
68+
<NgTranslate id={'TRANLATED_TEXT_ID'} substitutions={myController.getValue()} />
69+
</p>
70+
</>
71+
);
72+
};
73+
```
74+
75+
#### Wrap your React component
76+
77+
```js
78+
// AngularJS Component
79+
import * as angular from 'angular';
80+
import { angularize } from '@ng2react/support';
81+
import { MyReactComponent } from './MyReactComponent.jsx';
82+
83+
const myApp = angular.module('myApp', []);
84+
angularize(MyReactElement, {
85+
module: myApp,
86+
name: 'myAngularComponent',
87+
bindings: {
88+
title: '@',
89+
},
90+
require: {
91+
myController: '^myController',
92+
},
93+
replace: true,
94+
});
95+
```

‎docs/images/icon.png

606 KB
Loading

‎docs/images/todolist-conversion-example.png

640 KB
Loading

‎docs/ng2react-support.md

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# @ng2react/support
2+
3+
Library of helper utils for AngularJS to React migration
4+
5+
Based on code found in [react-in-angularjs](https://github.com/xjpro/react-in-angularjs)
6+
7+
## Installation
8+
9+
```bash
10+
npm install --save @ng2react/support
11+
```
12+
13+
## Usage
14+
15+
### Convert your AngularJS component or directive to React
16+
17+
You may do this manually or with the help of the [ng2react vscode extension](https://marketplace.visualstudio.com/items?itemName=maxbilbow.ng2react-vscode)
18+
19+
```jsx
20+
// React Component
21+
import React, { useState } from 'react'
22+
import { useService, NgTranslate } from '@ng2react/support'
23+
24+
const MyReactComponent = ({ title, myController }) => {
25+
const myService = useService('myService')
26+
const [state, setState] = useState(myService.getState())
27+
return (
28+
<>
29+
<h1>{title}</h1>
30+
<p>{state}</p>
31+
<p>
32+
<NgTranslate id={'TRANLATED_TEXT_ID'} substitutions={myController.getValue()} />
33+
</p>
34+
</>
35+
)
36+
}
37+
```
38+
39+
### Wrap your React component
40+
41+
```js
42+
// AngularJS Component
43+
import * as angular from 'angular'
44+
import { angularize } from '@ng2react/support'
45+
import { MyReactComponent } from './MyReactComponent.jsx'
46+
47+
const myApp = angular.module('myApp', [])
48+
angularize(MyReactElement, {
49+
module: myApp,
50+
name: 'myAngularComponent',
51+
bindings: {
52+
title: '@',
53+
},
54+
require: {
55+
myController: '^myController',
56+
},
57+
})
58+
```
59+
60+
### 2-Way Bindings
61+
62+
2-way bindings will not work automatically in react. To maintain this behaviour, you will have to
63+
manually call an update callback from within the React component and trigger the Angular digest cycle
64+
from the parent.
65+
66+
`angularize` can handle this for you:
67+
68+
```tsx
69+
const MyReactComponent = ({ myState, updateMyState }) => {
70+
return <input onChange={(e) => updateMyState(e.target.value)} value={myState} />
71+
}
72+
73+
angularize(MyReactElement, {
74+
name: 'myAngularComponent',
75+
bindings: {
76+
myState: ['=', 'updateMyState'],
77+
},
78+
})
79+
```

‎docs/requirements.txt

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
# jinja2==2.11.3
2-
# markupsafe==1.1.1
3-
# Markdown==2.6.11
1+
jinja2==2.11.3
2+
markupsafe==1.1.1
3+
Markdown==2.6.11

‎mkdocs.yml

+12-1
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,17 @@ site_url: https://marketplace.visualstudio.com/items?itemName=maxbilbow.ng2react
33
nav:
44
- Home: index.md
55
- Arc24: arc42.md
6+
- Extensions: VSCode.md
7+
- "@ng2react/support": ng2react-support.md
68
- About: about.md
79
- MkDocs: MkDocs.md
8-
theme: readthedocs
10+
theme:
11+
name: readthedocs
12+
highlightjs: true
13+
hljs_languages:
14+
- yaml
15+
- rust
16+
- tsx
17+
- jsx
18+
- typescript
19+
- javascript

0 commit comments

Comments
 (0)