# Local Development

For local development you can use the STLSe libraries that allows you to connect your module in real time to the STLSe applications

## Creating a module

1. First make sure that you have created a scope and a new module in the STLSe Admin Panel.  
In this example we will use the scope "stlse" and module slug "hello_world"

2. Create a new nx workspace  
`yarn create nx-workspace --preset=apps`  
For more information about nx please visit: https://nx.dev/

3. Enter your project folder and add dependencies  
`cd {workspace-name}`  
`yarn add @stlse/backend-connector @stlse/frontend-connector @stlse/modules-nx`  
`yarn add @nx/node @nx/react @nx/webpack`  
Also add the react-refresh package (Further described in the "Troubleshooting" section)  
`yarn add -D @pmmmwh/react-refresh-webpack-plugin react-refresh`  

4. Create your hello world module  
`yarn nx g @stlse/modules-nx:new`  
The command will ask you for the scope (e.g. `stlse`)  
Then will ask you for the module slug (e.g. `hello_world`)

5. Ensure fetched packages are properly linked by running:  
`yarn` 

After you've created your new module you will need to provide a "secret" so that you can connect it to STLSe.

6. Go back to the STLSe Admin Panel and create a new module if you don't have one already. You will find a "External module deployment" section, press "ADD VERSION"  

7. Set the version  
e.g. `0.0.01`  

8. Set the backend host to a subdomain of `.tunnel.local` and leave the port to 80 which will allow you to connect through tunnel to STLSe    
e.g. `stlse__hello_world.tunnel.local` - port: `80`

9. Set the frontend host to a localhost address where it will find your module-entry.js file from the frontend development server by default you should find it at:   
`http://localhost:4200/module-entry.js`

10. Save the external version, and the button "SECRET" button should appear, press it, it will generate a secret that you can copy and use it to connect your local module development to STLSe.
Paste it into the `remote` field inside the file at: `modules/{scope}/{slug}/backend/src/environemnts/enviroment.ts`

11. Now you can start your local development session by running:  
`yarn nx serve modules-{scope}-{slug}`  
This will start the development session for **BOTH** the backend and frontend parts  
e.g. `yarn nx serve modules-stlse-hello-world`  
NOTE: if you have underscores in your names they should be inserted as dashes in this command

Now you can add your local module into an STLSe application. 

12. Create a new hello world STLSe application (same as in the quickstart example) with:
- the authentication module set to `@hello_world/allow_all_login` at latest version
- theme module set to `@hello_world/hello_world_theme` at latest version
- the current module you just started with the external version you've set prior  
  (from our example it should be: `@stlse/hello_world` at version `0.0.01`)

13. Add a domain to your application and open it in a new browser. Now you should see your hello world application

For any question/correction please visit https://discuss.stlse.com

## SSR module

To create an SSR module the steps are the same as above but with a few small differences:

1. Install the following additional dependencies:  
- To bundle the module: `yarn add text-encoding url clean-webpack-plugin`  
- For module routing: `yarn add react-router-dom`  

2. Then you can create your hello world ssr module   
`yarn nx g @stlse/modules-nx:new-ssr`

3. Ensure fetched packages are properly linked by running:  
`yarn` 

From here the steps are the same.

Additionally you do not need a "frontend" address for you "External module deployment" configuration  
You only need to specify the backend tunnel address e.g. `stlse__hello_world.tunnel.local` - port: `80`

---
---

## Building and Uploading a module

Once you have finished developing your module, you have to build it and bundle into a zip to upload to STLSe

1. Build and bundle into a zip:  
`yarn nx build modules-{scope}-{slug}`  
e.g. `yarn nx build modules-stlse-hello-world`  
NOTE: if you have underscores in your names they should be inserted as dashes in this command

2. Go to the STLSe Admin Panel and open the edit page of your module. In the "Internal module deployments" section there should be a "UPLOAD VERSION" button, click on that button to open the upload process.

3. Set your module version, then select your zip file and press upload

4. Now that you have successfully uploaded your module, go to your application and change the version from the external development version to the internal uploaded version that you've just created


---
---

## Troubleshooting

Error:  
`Cannot find name 'use_filter'`   
Fix:  
Upgrade typescript:  
`yarn add typescript@~5.1.0`

Error:  
`NX   Cannot find module 'react-refresh/babel'`
Fix:  
Install react refresh package  
`yarn add -D @pmmmwh/react-refresh-webpack-plugin react-refresh`

Error:  
`Argument for '--jsx' option must be: 'preserve', 'react-native', 'react'.`  
Fix:  
Change `"jsx": "react-jsx"` to `"jsx": "react"`

Error:  
`server_URL is not a constructor`  
Fix:  
Ensure you have installed the yarn packages for SSR modules:  
`yarn add text-encoding url clean-webpack-plugin`  

Error:  
`TypeError: Cannot set property closed of #<Readable> which has only a getter`  
`at FsReadStream.close (/node_modules/memfs/lib/volume.js:2047:17)`  
Fix:  
Install/update `yarn add memfs`

Error:  
`TypeError: Cannot set property closed of #<Readable> which has only a getter`  
`at FsReadStream.close (/root/workspace/app/node_modules/webpack-dev-middleware/node_modules/memfs/lib/volume.js:2047:17)`  
Fix:  
Install/update `yarn add memfs` and add it to resolutions in package.js:  
```
"resolutions": {
  "memfs": "4.6.0"
}
```

Error with react types:  
`Types of property 'key' are incompatible.`  
Fix:  
Add resolutions to your package.json, e.g:
```
"resolutions": {
  "@types/react": "18.2.14",
  "@types/react-dom": "18.2.6"
},
```