Should add User Documentation

[LukeSavefrogs]

I find this project very interesting. 🥇

I find it very hard to start using it though, because of the lack of user documentation. I have questions like:

1. What is the entry point of the script (so the file i should start editing to get started)?
2. Where should i place my personal code?
3. What are all those extra files like ./src/operations.ts, ./src/site.ts, etc.? What should i do with them? And how can i use them to customize the experience?

I could help setting up the Documentation if you want, but i need help understanding the base structure first.

Going through the examples you linked didn't help, unfortunately 😕

[SimonAlling]

Thanks for submitting this issue – I agree that the documentation is indeed subpar. I'll try to answer your questions, for starters.

1. What is the entry point of the script (so the file i should start editing to get started)?

I think this is the best way to start building a userscript:

$ npm install --global userscripter
$ mkdir my-userscript
$ cd my-userscript
$ userscripter init
$ npm install
$ echo "node_modules/" > .gitignore # due to an issue solved in #67 but not published atm
$ git init
$ git add .
$ git commit -m "Initial commit"

At this point, you most likely want to start editing src/userscript.ts, src/operations.ts, and/or src/stylesheets.ts (see Example Userscript for inspiration). The entry point of the userscript itself is src/main.ts, but I typically don't edit it much.

2. Where should i place my personal code?

Short answer: Anywhere in src/. :slightly_smiling_face:

Long answer: The files created by userscripter init are just a suggestion; you can use any structure you want for your business code. The key is the userscripter.run call in the entry module, which is src/main.ts by default. The argument to userscripter.run can be constructed in any way you like – Userscripter imposes no restrictions on the contents of src/, except that it uses main.ts as the entry point for the userscript by default.

For small userscripts, I typically write my operations "inline" in src/operations.ts and my styles in src/stylesheets.ts. For large userscripts, I write them in separate files and import them in said files.

3. What are all those extra files like ./src/operations.ts, ./src/site.ts, etc.? What should i do with them? And how can i use them to customize the experience?

They're part of a boilerplate structure that I've used throughout my userscripts:

File name	Purpose
main.ts	Webpack entry point
userscript.ts	Userscript metadata
operations.ts	Operations performed by userscript (modifying the DOM etc)
stylesheets.ts	Styles inserted by userscript
config.ts	Constants chosen at will by the userscript author
site.ts	Constants that have to match the host site in some way
preferences.ts	User-facing preferences (for more complex userscripts)

You don't have to use that structure if you don't want to. As long as you keep main.ts and the userscripter.run call in it, you can use any structure you want. :slightly_smiling_face:

💡 Writing this comment gave me an idea: userscripter init could perhaps offer a choice between a "simple" userscript, with everything required to get started in a single file (src/main.ts), and a "complex" one, which could be the same as today.

[LukeSavefrogs]

Thanks for taking your time to write this introduction! It really helped me understand the basics of how it works!

In my opinion, the table you wrote should be in the README.md since it's so useful...

💡 Writing this comment gave me an idea: userscripter init could perhaps offer a choice between a "simple" userscript, with everything required to get started in a single file (src/main.ts), and a "complex" one, which could be the same as today.

This would be a great idea, it would help a lot to build just what you want and it would simplify the learning curve😀