Missing simple examples for new users

[steve-taylor]

I have never used jscodeshift, but have identified it as being potentially useful for a couple of simple use cases.

For example, I would like to change an object literal in code.

Before:

// Some code ...

const someObj = {
  x: {
    foo: 3
  }
};

// Some more code ...

After:

// Some code ...

const someObj = {
  x: {
    foo: 4,
    bar: '5'
  }
};

// Some more code ...

But there are no examples of changing values. In general, this repo is very thin on examples. Google and Stackoverflow don't seem to point to any relevant information. None of the linked examples are helpful. jscodeshift-helper doesn't help. Every example I have found so far is for complex use cases rather than something simple like changing the literal value of something.

[fkling]

Do you have any concrete proposals?

---

I agree that there should be easier ways to perform simple changes. E.g. for your case it would be very easy to write a generic setProperty('x', value) helper method for ObjectExpressions.

If you don't actually want to perform complex operations, something like http://www.graspjs.com/ might be more useful for you.

But in general, the approach to performing any transformation is the following:

1. Make yourself familiar with the structure of the AST node you want to modify.
2. Find the specific node you want to change (which might also require making yourself familiar with other node structures).
3. Build a new AST node.
4. Replace the node (or one of it's properties).

https://astexplorer.net can help with all these things.

In your example you want to change the value of a property in an object literal. The structure of an object literal node is

 {
    "type": "ObjectExpression",
    "properties": [{
        "type": "Property",
        "method": false,
        "shorthand": false,
        "computed": false,
        "key": {
            "type": "Identifier",
            "name": "x"
        },
        "value": ...
    }]
 }

Properties are listed in an array, so in order to change the value for x, you might have to iterate over the array and find the property where name is x, and change that nodes value property.

Complete example for your case: https://astexplorer.net/#/gist/baf3cd93afc1da2ee06e4243b35a0a5d/2353dde05858ef4d7e08f9d994817568f13622a2

[pushred]

Another beginner here! I managed to be productive and make several codemods dealing with import/require statements, with a bit under a day's work. I used AST Explorer and dug around ast-types and jscodeshift repos, mainly trying to hunt down the builder methods I needed and their signatures. The ast-types unit tests were most helpful here.

The difference between the builder methods and the AST/find arguments has been generally confusing.

One thing that I'm still trying to figure out is creating an object property using the shorthand syntax, as part of transforming a destructured CommonJS require. I see this in the AST but looking at the builder source for shorthand I find this. But another builder of the same property name exists and I'm currently hunting down what name this es6 version is exported as.

jscodeshift.api ← src/core/enrichCore ← recast/lib/types ← ast-types/main ← ast-types/fork

Still trying to understand what fork does and whether the es6/property builder I seek is even available in this context. Ultimately it's a cosmetic issue and maybe I would better be served by Prettier or even grasp for something like this. But I've been sold on jscodeshift as the safest way of doing these changes.

I would love to help with documentation of the builders or perhaps an addition to AST Explorer that fills this gap, if just for my future self! I'm curious if this is considered an ast-types issue however.

[davidmccabe]

Another beginner here. There aren't even examples of how to build new AST nodes. The readme points to the definitions of the AST builders, but it's not at all transparent how to figure out what you actually need to do based on these definitions. To the fields represent positional arguments? Properties in an object? Who knows?

[marvin-solano]

Very powerful tool, unfortunately the lack of documentation makes it extremely hard to start working with.

[NickHeiner]

The documentation for this tool is sorely lacking. I have to spend a lot of time reading the source, or reading examples of other working codemods, to figure out how thing work.

[danielo515]

More than new examples I think the docs should be improved and unified. It's very frustrating to not know where to look at for docs. The readme points you to a set of different repos, where some of those point to other repositories where there is no documentation at all. You have to figure yourself by reading all those source codes which methods lands on the jscodeshift api and which parameters they take. It's a super, super frustrating trial and error, and error, and error experience. For example, something as simple as creating an objectProperty with its shorthand property set to true leaves you scratching your head.

[NickHeiner]

That’s a perfect description of my experience as well.

On Fri, Dec 4, 2020 at 23:24 Daniel Rodríguez Rivero < notifications@github.com> wrote:

More than new examples I think the docs should be improved and unified. It's very frustrating to not know where to look at for docs. The readme points you to a set of different repos, where some of those point to other repositories where there is no documentation at all. You have to figure yourself by reading all those source codes which methods lands on the jscodeshift api and which parameters they take. It's a super, super frustrating trial and error, and error, and error experience. For example, something as simple as creating an objectProperty with its shorthand property set to true leaves you scratching your head.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/facebook/jscodeshift/issues/193#issuecomment-739138899, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAGKTA663OE43DEOWCT6RM3STHNZ3ANCNFSM4DHG4L5Q .

[mbrookes]

@davidmccabe

There aren't even examples of how to build new AST nodes.

This blog post: https://www.toptal.com/javascript/write-code-to-rewrite-your-code, and this tool: https://rajasegar.github.io/ast-builder/ (used in conjunction with AST Explorer) are your friends.

More posts and examples here: https://github.com/sejoker/awesome-jscodeshift, but I can't vouch for them.

@pushred

One thing that I'm still trying to figure out is creating an object property using the shorthand syntax

@danielo515

something as simple as creating an objectProperty with its shorthand property set to true leaves you scratching your head.

Here you go:

const property = j.objectProperty(
   j.identifier('name'),
   j.identifier('name'),
);
property.shorthand = true;

[danielo515]

This blog post: https://www.toptal.com/javascript/write-code-to-rewrite-your-code, and this tool: https://rajasegar.github.io/ast-builder/ (used in conjunction with AST builder) are your friends.

More posts and examples here: https://github.com/sejoker/awesome-jscodeshift, but I can't vouch for them.

Indeed, those a re great resources that I ended finding and using afterh ours of frustration. The thing is that all that process can be streamlined a lot if such examples were part of this repository instead of third party blog posts and tools. It is nice that people is writing such good stuff out there, but that doesn't make having that information, essential for beginners, as part of this repository.

[danieldelcore]

Hey all, I've been working on a project called CodeshiftCommunity 🚚, based on jscodeshift, which is provides some docs/guides/recipes for creating codemods. It's still early days for the project as a whole, but at the very least these docs should be helpful to folks like me that had no idea where to get started 😄

Feedback welcome!

Guides

• Your first codemod
• Understanding ASTs
• Prompting for human input
• When not to codemod

Recipes Practical examples for common operations

• Working with imports
• Working with react + JSX

The long-term plan is to be a place where people can learn how to write codemods, publish in a way that's similar to DefinitelyTyped and consume them via cli.

[danielo515]

This is fantastic! Thank you so much

On Mon, May 17, 2021 at 8:31 AM Daniel Del Core @.***> wrote:

Hey all, I've been working on a project called CodeshiftCommunity 🚚 https://www.codeshiftcommunity.com/docs/, based on jscodeshift, which is provides some docs/guides/recipes for creating codemods. It's still early days for the project as a whole, but at the very least these docs should be helpful to folks like me that had no idea where to get started 😄

Feedback welcome!

Guides

• Your first codemod https://www.codeshiftcommunity.com/docs/your-first-codemod
• Understanding ASTs https://www.codeshiftcommunity.com/docs/understanding-asts
• Prompting for human input https://www.codeshiftcommunity.com/docs/prompting-for-human-input

Recipes Practical examples for common operations

• Working with imports https://www.codeshiftcommunity.com/docs/import-manipulation
• Working with react + JSX https://www.codeshiftcommunity.com/docs/react

The long-term plan is to be a place where people can learn how to write codemods, publish in a way that's similar to DefinitelyTyped and consume them via cli.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/facebook/jscodeshift/issues/193#issuecomment-842038269, or unsubscribe https://github.com/notifications/unsubscribe-auth/AARKJWN6CQJFKSF2VPABICDTOCZ3RANCNFSM4DHG4L5Q .

--

https://danielorodriguez.com